On Fri, 21 Feb 2003, Eduard Bloch wrote: > #include <hallo.h> > * John Summerfield [Fri, Feb 21 2003, 02:10:57PM]: > > > > to be a lot of interest, but not too much concrete input. Maybe > > > one of the issues is there are so many ways to get it to work? > > > > If I were to write it (assuming I knew enough, which at present I don't), you > > could probably point out errors, but not the inadequacies. > > > > At present, I in my ignorance am well-equipped to locate the latter. If I wait > > until I have worked through it and found a path that works, then it will become > > clear enough that I will no longer be able to indentify clearly what's missing, > > what facts I have assumed but which might not be known to others. > > What about making notices on your way? Later, you can review them and > remember what caused the problems and how another person may solve the > problem easier.
In my experience, and the experience of others, good documentation can only be written by someone who knows and understands the topic well. This is why authors such as Colleen McCullouch (she spent 13 years researching before writing "First Man in Rome") spend so much time in research. While I could muddle my way through, at the end of it I would not have as good a document as I would expect others here would produce. I see my my greatest value in this as a checker; at present I won't make the same assumptions someone to whom it's a trivial undertaking to make. -- Cheers John Summerfield Please, no off-list mail. It won't be read, it will be handled as spam. -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]
