Re: GDP question about piano templates & dynamics

[Graham Percival]

On Sat, 28 Jun 2008 19:43:44 +0200
"Valentin Villenave" <address@hidden> wrote:

> 2008/6/28 Neil Puttock <address@hidden>:
> 
> > I wish that were the case; got any tips on working faster (without
> > causing massive breakage)? :)

Focus.  Let's say that you're working on \underline:
- does this command take 1 argument or more?  It's one.  So copy
  the previous one-argument example:
\markup {
  one \\bold two
}
and change the \\bold to \\underline.  Boom, example done.  Next
command.  Assuming that you keep that previous example in your
copy buffer, the entire command can be done in 30 seconds.

- go through the entire list, just taking care of simple stuff.
  Don't play with examples.  For example, you noticed that the
\box command looks ugly if you don't \override the padding.  Don't
fix that stuff yet.  Just go through the list making the examples.

- if there's a command with multiple arguments, dump a FIXME
  there.  And then move on.  Don't think about it.

- once you've gone through the list, start compiling the docs and
  go get coffee.  When you come back, hopefully they'll be done.
skim through the html pages; if you see something ugly (like
\box), *then* go back and fiddle with the example.


This is how you can cover 90% of the docs in an hour.  It's dull,
it's repetitive, but it gets stuff done.


Then you do the same thing for multi-argument commands.  Now the
.scm file is a mixture of finished and unfinished commands, but
you don't need to search for commands to fill in -- you just
search for FIXME.  Here's your basic example:
\markup {
  \command {
    one
    two
  }
}

If you can shove a markup command into the above format, do it and
stop thinking about it.  If you can't, leave the FIXME alone and
move on to the next one.  Again, DON'T THINK ABOUT IT.

- compile docs, get coffee, fix remaining.


At this point there's probably about 10 commands left.  They'll
require special attention, though, reading source code, asking on
-devel, whatever.  But that's fine... it's a short list.  The end
is in sight.  You might be able to farm out one or two of these to
other people if it's too hard (this is a general tip, I don't
think it'll apply to you).

Also, I'm much happier, because the docs look pretty complete; I
can see that there's only a few things left.  If you fell off the
edge of the Earth, I know that I can finish the remaining commands
myself.

> Similarly, I'm looking for tips on how to write sensible docs on hairy
> stuff such as 1.8 Text :)

Here, the big question is figuring out what you don't need to
discuss.  At the moment, you're thinking about explaining all the
different text alignment commands, because they aren't in the
appendix.  Once Neil has added all those examples -- and these
definitely do fall into the "trivial multi-arg commands" category,
and therefore only take an hour -- I suspect that we'll find that
you don't need to discuss them.

Basically, stop thinking about "explaining everything there is to
do about text".  Instead, think about "explain enough abotu text
so that users can understand the \markup command reference in the
appendix".

Again, this is much easier if you can actually *see* what the
command reference looks like... but if you can't, you just need to
imagine it.  That's what I have to do all the time, with the
possibility of snippets, new texi2html output, deciding what to
cover in the LM vs. the NR, etc.

> (I've just seen Nicolas has made my font-size docs nearly obsolete
> less than an hour ago; I'm both thrilled and desperate.)

If your font-size docs were written properly, it should only take
a few minutes to update them.

Cheers,
- Graham