On Thu, Aug 13, 2009 at 04:54:15PM -0700, David Fedoruk wrote: > Also, remember that my time zone is GMT -8, so I am one of the last > people on this list to see anything posted.
Same here, being in Burnaby. > If I had to say one thing that is wrong with documentation is that the > people doing the documentation assume to much about the state of the > reader's knowledge. What may seem obvious to you, may not be to the > person reading your documentation. I disagree here. We spent a lot of time thinking, talking, and planning out those assumptions. At the beginning of the Learning Manual, we assume that the reader knows nothing other than having a slight familiarity with their operating system. (i.e. windows users should know what a "double-click" is) In the middle of the LM, we assume that the reader has read (and understood) the earlier parts** of the LM -- or at least, that the reader would be willing to go back and review previous material. I agree this assumption is slightly tenuous, but if we couldn't make this assumption, the docs could easily be three times as long. ** if you find any instance where this is not true, please let us know! The LM is designed to be read sequentially, explaining each term and concept as they come... we consider any deviation from this to be a serious problem. In the Notation Reference, we assume that the user has read (and understood) the LM. Again, maybe this is a flawed assumption, but again, we could triple the doc lenth (not to mention the doc writers' workload!) otherwise. In the Internals Reference, we assume that people know a lot. Partly because this is advanced stuff, but mostly because we don't have enough doc writer effort to smooth this over. Cheers, - Graham _______________________________________________ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
