Re: GDP: welcome, helpers!

[Michael Rasmussen]

Graham Percival wrote:
> I've posted initial instructions for GDP helpers here:
> http://opihi.cs.uvic.ca/~gperciva/helper.txt
> 
> If somebody could send those to the list (as a reply to this), that 
> would make it easier for other people to read.
 
The instructions:

Sorry again for the delay in getting this part organized.  We still have
some technical problems, but resolving those will probably take at least
a month.  I've identified some things that we can work on, which won't
depend on whether or not the technical stuff is fixed.


TRIVIAL/EASY HELPERS

We're going to work on these sections at first:
  Tutorial
  Pitches
  Rhythms
  Expressive marks
  Simultaneous notes
  Staff notation
  Educational use

I'm still finalizing your exact instructions (see the email "GDP:
documentation guidelines"), but it will probably take a week to get into
our workflow.

The plan is this: you all sign up for one section (first-come,
first-choose; send emails to both me and the list, so you can see what
other people have chosen).  Then you work on that section for one week.
At the end of that week, you send me whatever you've done, and I'll
put it back together.  Then you all pick another section, and do similar
work on that.

I hope to have each section examined at least three times.  It's not
that I don't trust you, it's that... well, ok, I don't trust you.  :)
But in this context, I don't even trust myself: I always thought that I
was careful to write the docs correctly, but I've found many many
mistakes in my previous work.

Another reason why we will rotate the sections like this is to reduce
stress.  When you go through the docs, fix what you can, but if
something is too confusing, you can leave it for the next person.  For
example, if you don't feel confident about fixing English grammar, you
could leave a comment that a rewrite was necessary, and simply continue
fixing the formatting issues.  Alternatively, if you are confident about
grammar but not LilyPond input, feel free to concentrate on the grammar
and ignore lilypond stuff.


WORKING

If you're comfortable with git (or svn/cvs) or diff, let me know.  I'm
assuming that you're not familiar with those programs, so don't worry if
you've never heard of them before.

Take a look at the files here:
http://opihi.cs.uvic.ca/~gperciva/gdp/

These are the source files of the documentation.  Pick one -- say,
tutorial.itely -- and compare that text file with the pdf or html docs.
You should be able to pick out a few major things:
@node Foo
@subsection Foo

is a standard portion of the documentation.

@lilypond[blah,blah,blah]
...
@end lilypond

produces a lilypond example.

@ref{other_section_name} produces a link to that section.


The language is called texinfo; you can see its manual here:
http://www.gnu.org/software/texinfo/manual/texinfo/

but you don't _need_ to read those docs.  The most important thing to
notice is that text is text.  If you see a mistake in the text, you can
fix it.  If you want to change the order of something, you can
cut-and-paste that stuff into a new location.


Try downloading one of the files (ideally the one that you're planning
on picking -- for example, if you want to work on Rhythms, download
rhythms.itely) and make a few small changes with a text editor, then
send it back to me.

I should repeat: make a FEW, SMALL changes.  It will probably take a few
tries until we're comfortable working on the .itely files, so I might
need to say "sorry, that didn't work.  Please download the file again,
make those changes (in a slightly different way), then send me the new
file".



MEDIUM HELPERS

You should probably follow the same steps as the trivial/easy people (in
regards to downloading a file and sending me an updated file), just for
practice.  The following items have priority:

- tutorial 2.4 Songs.  This is the weakest part of the tutorial; does
  anybody want to rewrite or add more material here?
- polyphony: we need to move some (or all) of the explanations into the
  Learning Manual (particularly Fundamental concepts).  Volunteers?
- take a careful look at Pitches and Rhythms; find broken examples, make
  a list of new things we should cover, start planning a rewrite of any
  sections which are too complicated.

If you're interested in the third point, just make notes by yourself for
now.  I'll post a more in-depth examination of those two sections in a
few days, and the discussion can progress from there.


Trevor, IIRC you didn't officially sign up as a helper, but you're in
charge of the "Inspirational Headwords".  If you could come up with
something for Pitches and Rhythms soon, that would be awesome.  Remember
that these don't need to be existing, famous pieces of music; a portion
of your own compositions would be great for Rhythms.  Also remember that
we can always update stuff later.  Let's get something to slap in there
to demonstrate the concept.  :)

Cheers,
- Graham 

-- 
      Michael Rasmussen, Portland Oregon  
    Be appropriate && Follow your curiosity
          http://www.patch.com/words/ 
  The fortune cookie says:
Science is what happens when preconception meets verification.