Re: User Documentation Requirements



On Fri, 2006-10-20 at 00:47 -0600, Elijah Newren wrote:
> On 10/19/06, Shaun McCance <shaunm gnome org> wrote:
> > In the 2.15 release cycle, we moved the new module proposal
> > period to the beginning of the release cycle
> <snip>
> > This was an incredibly good idea, and whoever thought of it
> > should get a big pat on the back.
> 
> IIRC, it was Jeff's idea.  And I agree, it was a great idea.
> 
> <snipped user-documentation proposal>
> 
> > I am half-tempted to attempt to standardize the name of
> > this [bugzilla documentation] component, but I'd want to
> > talk to bugmasters first to see how easily we could transition.
> 
> It looks like I filed this issue in response to previous comments on
> the matter as bug 338663.  I agree with Olav's comments there; it
> shouldn't be hard to make this transition...other than one notable
> exception: I don't know how to resolve
> http://bugzilla.gnome.org/show_bug.cgi?id=339173.  That kind of breaks
> the almost-standard[1] 'docs' naming convention.  The are several
> proposed possible solutions, but it doesn't seem very clear to me
> which one should be used (if any).

I'm also half-tempted to try to push 'help' as the standard
component name, even though 'docs' is the de facto standard
right now.  We advise using 'help' as the directory name for
user documentation, so it sort of makes sense.  (I will also
likely push to standardize that directory name, but only after
we've transitioned to a VCS that can track changes across file
moves.)

(Moving from 'docs' to 'help' as the component name would leave
us with very awkwardly-named docs-maint aliases, so...)

For multi-program modules, if they do multiple help components,
they could be named prog-help.  Or would help-prog be better,
because they'd be easy to shift-select when alphabetized?

> > Objections?
> 
> None here.  One question though...if this user-documentation proposal
> is agreed upon, is this something that we want to start
> applying/enforcing in 2.18 or 2.20?  It seems we often have
> suggestions in one cycle and then they start getting applied/enforced
> in the next cycle (perhaps after some additional discussion early in
> the next cycle), but it's still relatively early in 2.18.

I think it's early enough that we could get started with it
right now, if we have buy-in.  This affects the majority of
our maintainers, so I would like to hear from them.  What I
don't want is a ruling from on-high.  I want the maintainers
to be in.

--
Shaun





[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]