Writing documentation for ngspice
Ngspice is really a complex software, and it is almost impossible to use it without a manual. A manual for ngspice does not exist yet. Anyway (we are fortunate) many good texts and manuals have been written on spice and can be used with ngspice. Then you may ask:
Why do we need to write documentation ?
Because ngspice has many improvements over the original spice3 and there is little or no documentation at all for them.
In writing documentation for ngspice we should take into account that, while online docs are good for reference while using the program, printed documents are more readable (many people do not like to read docs on computer monitor) and both types of documentation are equally important. It is important, for maintenance, that both printed and on-line documentation can be produced from the same source.
Among the documentation system that can be used are:
- Texinfo: Texinfo is the official documentation format of the GNU Project. Texinfo uses a single source file to produce output in a number of formats, both online and printed (dvi, html, info, pdf, xml, etc.).
- TeX / LaTeX: TeX / LaTeX are typesetting systems designed for high-quality composition of material that contains a lot of mathematical and technical expressions.
- DocBook: DocBook provides a system for writing structured documents using SGML or XML. It is particularly well-suited to books and papers about computer hardware and software,
DocBook seems the most promising, it is tailored to write books and manuals on computer science and software, is flexible enough to produce online and printed documentation and there are a plenty of tool on every platform that support it. DocBook is an emerging standard for software documentation. Two interesting links are:
