Several people have already made the point not to use too much jargon or specialty knowlage in your documentation. But if you can't do that (because you don't feel like, or don't have the time to, explain what your module/program does in lay terms, or because you simply aren't that good of a writer), at least explain where the terminology you use /is/ documented, preferably on the web. For example, I'm (attempting to) write a module to nicely parse MIDL files into parameter lists for Win32::COM (which I don't link to because I havn't finished writing it). Now, I'm not going to explain all of MIDL's syntax and keywords, because I don't feel like repeating Microsoft's and the OMG's documentation on the matter, but also because some of it simply isn't very relevant, and some I don't even understand fully -- I just attempt to cleanly ignore. So, in my documentation (which I've only just begun to write), I make a lot of references. It isn't exactly a /good/ thing, but it's better then the alternitive.
In reply to Re: Writing Good Documentation
by theorbtwo
in thread Writing Good Documentation
by defyance
| For: | Use: | ||
| & | & | ||
| < | < | ||
| > | > | ||
| [ | [ | ||
| ] | ] |