| [ << Documentation work ] | [Top][Contents] | [ Website work >> ] |
| [ < Technical writing style ] | [ Up : Documentation work ] | [ Scripts to ease doc work > ] |
5.6 Tips for writing docs
In the NR, I highly recommend focusing on one subsection at a time. For each subsection,
- check the mundane formatting. Are the headings (@predefined, @morerefs, etc.) in the right order?
- add any appropriate index entries.
- check the links in the @morerefs section – links to music glossary, internal references, and other NR sections are the main concern. Check for potential additions.
- move LSR-worthy material into LSR. Add the snippet, delete the material from the ‘.itely’ file, and add a @lilypondfile command.
- check the examples and descriptions. Do they still work? Do not assume that the existing text is accurate/complete; some of the manual is highly out of date.
- is the material in the @knownissues still accurate?
- can the examples be improved (made more explanatory), or is there any missing info? (feel free to ask specific questions on -user; a couple of people claimed to be interesting in being “consultants” who would help with such questions)
In general, I favor short text explanations with good examples – “an example is worth a thousand words”. When I worked on the docs, I spent about half my time just working on those tiny lilypond examples. Making easily-understandable examples is much harder than it looks.
Tweaks
In general, any \set or \override commands should go in the “select snippets” section, which means that they should go in LSR and not the ‘.itely’ file. For some cases, the command obviously belongs in the “main text” (i.e., not inside @predefined or @morerefs or whatever) – instrument names are a good example of this.
\set Staff.instrumentName = "foo"
On the other side of this,
\override Score.Hairpin.after-line-breaking = ##t
clearly belongs in LSR.
I’m quite willing to discuss specific cases if you think that a tweaks needs to be in the main text. But items that can go into LSR are easier to maintain, so I’d like to move as much as possible into there.
It would be “nice” if you spent a lot of time crafting nice tweaks for users… but my recommendation is not to do this. There’s a lot of doc work to do without adding examples of tweaks. Tweak examples can easily be added by normal users by adding them to the LSR.
One place where a documentation writer can profitably spend time writing or upgrading tweaks is creating tweaks to deal with known issues. It would be ideal if every significant known issue had a workaround to avoid the difficulty.
See also
| [ << Documentation work ] | [Top][Contents] | [ Website work >> ] |
| [ < Technical writing style ] | [ Up : Documentation work ] | [ Scripts to ease doc work > ] |