pcb-rnd knowledge pool
pcb-rnd documentation policy
| doc_and_code by Tibor 'Igor2' Palinkas on 2018-11-04 | Tags: insight, doc, documentation, user, manual, doxygen, wiki, markdown, html |
Abstract: Explanation of high and low level documentation; pcb-rnd policy on not mixing source code with high level documentation and not writing alibi docs.
Theory
Rule 1: Levels of documentation
There are many layers at varying details to be documented. The approach we use at pcb-rnd sorts documentation in two levels: high level and low level.
High level documentation explains the generic concept, trying to provide an overview on the whole topic, often with connections to related other topics. It does not dive down in small details. It often explains how things are designed, why things are like they are and how they can be used to solve practical problems.
Low level documentation assumes the reader already understands the concept and is looking for the technical details. Thus a low level document does not explain why the feature exists or how it can be used in practice but goes very deep into details of the bolts and screws of the actual implementation.
At pcb-rnd we generally prefer to separate high and low level documentation, even on file level.
Rule 2: User and developer documentation
An orthogonal split that affects most documentation is user vs. developer. We expect developers also know the user documentation but we do not expect users know any of the developer documentation.
User documentation is mainly about how to use the software. But as pcb-rnd is a hacker tool, we do assume the user wants to fully understand what (s)he is doing. Thus we do require users to understand:
- actions
- the data they manipulate (the data model)
- the generic aspects of pcb-rnd infrastructure, such as plugins and scripts
- sometimes even some file format details.
Rule 3: Code vs. documentation
Unlike some other projects, pcb-rnd does not believe that placing documentation in source code will help keeping the documentation up to date. However, it would definitely mean short, simple, clear code scattered with long sections of user documentation.
We absolutely avoid that and keep high level documentation and user documentation separate from code. This is one of the reasons why we do not use doxygen, or custom "extract document from code" tools, like geda/pcb's "start-doc/end-doc" system.
Rule 4: Simplicity, accessibility
Good document comes in a format that is easy to edit, easy to view/render and does not depend on megabytes of external tools for either. There are many formats fulfilling these requirements, and we settled with plain text and plain, hand written html (of the web1.0 kind).
We do not use markdown, wiki, texinfo, tex, docbook and other similar formats. They are not easier to edit than html1.0, but they do require a lot of tools just to get a proper render.
A gray area that we do accept, tho, is svg.
Note: html files are written in plain text using conventional text editors. We do not convert these htmls from any other sources and we do not use visual html editors for them.
Rule 5: No alibi
There are things so simple and trivial that they do not need any documentation. In that case, do not write documentation.
We do not need to have a specific kind of documentation for every item of something, just to be able to tick in a checkbox. We do not aim on some sort of virtual completeness: if some items do not have documentation, that doesn't necessarily mean the documentation is incomplete but often means it just doesn't need documentation.
Never write alibi docs: if you do not know how to document something, do not document it. Do not put there placeholders for missing documentation either. Do not write documentation that only repeats the obvious (e.g. argument names and types of a C function).
Practice
user documentation
The "low level" of our user documentation is the user manual that lives in trunk/doc/user as a large, modular html document. It optionally uses trunk/doc/user/default.css, but must properly render and must be 100% usable on browsers not supporting css, javascript or any web2.0.
The user manual is more about how pcb-rnd works. It should be relatively short and to-the-point, documenting facts clearly, but not explaining them too much - even if it makes the document a bit dry.
Accompanying the user documentation there are multiple "high level" documents helping the user to find their way.
Tutorials in trunk/doc/tutorials. These should explain how typical workflows are done. A good tutorial focuses on one topic and explains how/why things are done but spares details for the user manual (which it links to).
Another good source of high level information is the knowledge pool, which contains unorganized, random, but tagged and searchable articles.
code documentation: actions
One of the primary interfaces most parts of the code provide is actions. Actions come with some in-C-source description (that will be used for tab completion). This is the low level documentation. Keep it short.
The high level documentation that explains what the action is for and how to use it efficiently goes in a plain, headerless html in trunk/doc/user/09_appendix/action_src. Each file is for one action implementation. There are a few custom html tags introduced, which are processed and replaced when these files are read (but do not disturb rendering/viewing the files directly):
- <act> is an action reference (text is an action name, without any suffix or punctuation)
- <arg> is the name or value of an argument
- <example> is a single line of example code, typically action usage example
Keep a /* DOC: actionname.html */ reference above the action implementation in case there's a high level documentation available. If you modify an action source code that has such a reference, always check the referenced file and update it if it is out of sync in any way, even if the fixes are unrelated to your current task.
code documentation: C API
The low level documentation shall go in as-short-as-possible comments in the header file. We do not use unified function documentation templates, because they only make docs longer. The low level doc assumes the user knows how the subsystem works and want to learn how that specific API call is done. Document corner cases, side effects and non-trivial aspects. Do not document the obvious (e.g. argument names and types). A good example is src/event.h.
The high level documentation needs to be a separate html or even directory under trunk/doc/developer. It should explain the whole subsystem but should not reproduce the low level calls. A good small subsystem example is trunk/doc/developer/polygon.html; a good large subsystem example is trunk/doc/developer/plugin/.
We assume the programmer will read both the high level documentation and the low level API comments in the headers.
File formats: native, locally invented formats
Make sure to have a high level documentation under trunk/doc/developer/ that doesn't only define the low level syntax but also explains how to interpret data (unless it is explained already in another section of the documentation).
A good example of mostly self-contained explanation is trunk/doc/developer/ddrc.
A good example on providing a mostly low level syntax description then relying on external sources is trunk/doc/developer/lihata_format/. It does not explain how lihata works, because that is documented well in the lihata project. It does not explain how pcb-rnd's internal data model works because that is documented well in the user manual. It rather links these.
File formats: alien formats
Our main goal with alien format is to read and write them. While we want to have our code prepared to read anything valid, we generally want to be able to read practical files found in the wild, even if those files are not 100% in line with the file format specification.
A good alien format doc does not reproduce the original file format spec (unless it was unavailable and had to be reverse engineered). However, it does describe limitations, potential incompatibility, tricks we had to do and exotic, non-trivial cases found in the wild.
These documents are in trunk/doc/developer/alien_formats/.
A good example is trunk/doc/developer/alien_formats/geda_pcb.txt, which documents the pcb-rnd extensions that were made while this format was not yet alien.