Re: documentation help seriously needed

[Graham Percival]

In the doc source, we add commands like
  @cindex beaming
  @funindex []

There is no automatic testing for this, but I'm certain that our
doc build correctly links the index entry to the place where the
command was placed in the doc source.


As far as I know, there is nobody currently working on updating
these entries, checking for completeness, etc.  This isn't a hard
job, but it *does* require you to know git+compiling+our doc
policies.  It's not something that can be easily described in
words and handed off to another person to do the actual file
editing.

I have no plans to ask any current doc editors to undertake such a
job; I don't think the benefit outweighs the cost and effort.  But
if you're particularly keen to do it, we can train you to work on
this.

Cheers,
- Graham


On Mon, Mar 22, 2010 at 03:51:49PM -0600, Hugh Myers wrote:
> Graham,
> 
> My area of expertise is editing and one of the things that often make
> or break a set of docs are the indexes for each manual. Do we have any
> kind of regression scheme (sorry about the pun) to check for problems
> peculiar to an index? For instance does each citation in the index
> lead to a page with the word in context. Given a list of key words and
> concepts are they in the index? A lot of user questions can be met
> with a healthy does of RTFM but that becomes increasingly harder to do
> the thicker the manual(s) become(s). Some of this is problematic in
> that the best time to do this is with the text frozen--- this to avoid
> repeated toe-stepping-apon by repeated changes, deletions and
> additions.
> 
> --hsm
> 
> On Mon, Mar 22, 2010 at 3:16 PM, Graham Percival
> <address@hidden> wrote:
> > No, that's fine -- we already have somebody to handle the
> > git+compile+doc policy stuff.  So far I have no indication that
> > he's overwhelmed with work.
> >
> > If you're up for writing a few lilypond examples (say, creating an
> > example of \bendAfter using a non-integer argument), *that* could
> > be useful... but I'm pretty certain (... well, pretty *hopeful*,
> > at least)  that we'll have enough helpful users who can create
> > such examples.
> >
> > Maybe get back in touch in a week if there doesn't seem to be any
> > movement on this issue.  :)
> >
> > Cheers,
> > - Graham
> >
> > On Mon, Mar 22, 2010 at 03:53:12PM -0500, Jonathan Kulp wrote:
> >>    I should be able to handle some git committing / compile checking, and
> >>    stuff like that if others can do the worst of the typing.
> >>    Jon
> >>
> >>    On Mon, Mar 22, 2010 at 3:36 PM, Graham Percival
> >>    <address@hidden> wrote:
> >>
> >>      Here's the current situation with the documentation.
> >>
> >>      1. we have a number of users who know a lot about lilypond, but
> >>      A  are not familiar with git + compiling + our doc policies.
> >>      2. we have a doc editor on Windows who knows about
> >>      A  git+compiling+doc policies, but knows relatively little
> >>      A  about lilypond.
> >>      3. we have a number of open documentation issues, some of them
> >>      A  critical [1].
> >>
> >>      If you belong to category 1, and think you might be able to help
> >>      with category 3, please contact category 2 (CC'd on this email) or
> >>      me.
> >>
> >>      [1]
> >>      
> >> http://code.google.com/p/lilypond/issues/list?can=2&q=type=Documentation&sort=priority
> >>
> >>      Cheers,
> >>      - Graham
> >>
> >>      _______________________________________________
> >>      lilypond-user mailing list
> >>     address@hidden
> >>      http://lists.gnu.org/mailman/listinfo/lilypond-user
> >>
> >>    --
> >>    Jonathan Kulp
> >>    http://www.jonathankulp.com
> >
> >
> > _______________________________________________
> > lilypond-user mailing list
> > address@hidden
> > http://lists.gnu.org/mailman/listinfo/lilypond-user
> >