Propose an alternative to MS Office for technical documentation.
- sa7
The documentation format increases productivity in comparison to MS Office.
- s9o
,
The documentation format is not new. The documentation format is supported by a large open source community.
- s9v
It is possible to diff a documentation file with the version control system (VCS). Therefore it must be text-based.
- scf
Tools shall be available for conversion to the following formats
- HTML: to make the documentation viewable over the internet
- PDF: to archive a version and for printing
- DOCX and ODT: to satisfy existing procedures
The tools shall be
- open-source and community supported
- stable
- san
, , hyperlinks
The documentation items shall be marked by flat and unordered IDs.
Use these IDs to jump to documentation items inside the editor via a keyboard shortcut or a mouse click: hypertext.
Support hyperlinks in the formats the documentation can be converted to.
- stq
Full text search over all files with regular expressions shall be available from inside the editor for
- source code and
- documentation
- sed
The documentation can be opened by a normal text editor.
The documentation is easy to read and write in a text editor.
- s45
Support formatting:
paragraphs, sections with headers
enumerated and bullet lists, footnotes, citations, comments
bold, italic, typeface, hyperlinks
tables, images, figures, code listings, mathematics
The formatting
- is not obtrusive ()
- shall be intuitive
- does not need much learning
Table-like data is stored as text using a format that is
- not too verbose
- easily accessible by scripting ()
- sgt
,
Make it easy to automatically generate parts of documentation
- from source code
- from data
Data shall be usable
- in source code
- in documentation
- s0t
Automatically generate a dependencies file that shows how documentation items are linked. Warn about missing or duplicate targets.
- s8c
,
Provide means to integrate into the documentation
- defines that are also usable in source code
- calculation results
- s10
The project uses a version control system (VCS) like SVN or GIT.
Documentation history is handled by the VCS. Team members follow changes of documentation on the VCS.
- sxr
The project uses a build system.
Creation of documentation is integrated in the build system.
- s1g
Whenever something is used twice in code and documentation let it be generated from a master copy: constants, defines of structs, ...
- scs
All documentation of concern to development is integrated in the text-based documentation.
- risk analysis / motivation
- specification
- design description
- test plan
- issues
- meeting minutes
- ...
- sim
There is a readme document that informs, where to put and how to find which information.
- seo
The developer
- only works and cares about the text sources of documentation
- does not spend time in fixing formatting issues of a generated format
- sil
Developers can work independently.
This is linked to . The VCS needs to enable independent development. A distributed VCS like GIT has advantages in this regard.