21 Apr
2009
21 Apr
'09
2:24 p.m.
Jan Janak wrote:
On 21-04 10:41, Martin Hoffmann wrote:
I am quite aware of that. But the amount of familiarity with the code
necessary to write useful documentation differs. Modules like xlog or
acc are easy and even someone new to SER code can extract the necessary
information. tm is the other extreme. Figuring out what the module will
do with ACKs and CANCELs is a task for several hours.
But interstingly enough, this latter point also shows that documentation
written by developers is necessarily good either. Neither K nor SER
document the very subtle and occassionally unexpected behaviour.
Juha Heinanen wrote:
You actually have to understand the code to be able to document it
properly. Daniel-Constantin Mierla writes:
Why not? Everyone who can read code can write documentation. Granted, tm
is tricky, but the developers can read over it and point out mistakes. This is open source
and as soon as we get community involved, the project evolves much
better.
community is not able to write docs for common modules, e.g., tm. Sure, you can always hire a technical writer who will
produce
boilerplate like documentation, but I doubt that such documentation will be of
much use.
The main skill of a good technical writer is to ask the right questions.
Sure, they are a very rare breed, but if you happen to run across one,
you will afterwards understand your own code better.
Regards,
Martin