Quote:
Originally Posted by chaley
From this developer's viewpoint:
Writing documentation is hard. Bad technical writing takes time. Mediocre technical writing takes a lot of time. The time required by good technical writing can easily exceed the time taken to do the programming. The work isn't fun (and I do this to have fun). We get hassled over matters of style, clarity, organization, and typography, and sometimes accuracy. What we do write seems to be ignored, although I admit it is hard to know who *didn't* ask a question because of the docs.
We aren't dealing with contracts acceptance clauses; there is no commercial reason to write it.
For me, there are only two motivations to write documentation: to test the new stuff (do I understand what I am doing enough to describe it logically?), and boredom with coding. The first case is rare, and in the second case I would rather read.
I am mildly surprised that more people don't volunteer to do documentation. It requires no python/programming skills, can be done incrementally, is a good way to learn, would be actively supported by people, and is a fine way to contribute to the project.
|
A problem with writing accurate, detailed documentation when a program is under development is every time one changes or adds code, the documentation changes. Keeping up with both would be a nightmare (even the big commercial programs don't always get it right or, like Microsnot, don't bother with documentation at all). As I said, I would rather see work being done to improve calibre than on the documentation until calibre is pretty much finished (though I probably won't live that long).