System Requirements¶
Purpose¶
Propose an alternative to MS Office for technical documentation.
Requirements on Documentation¶
| sa7: | Productivity |
|---|
The documentation format increases productivity in comparison to MS Office.
| s9o: | Community, rj4 |
|---|
The documentation format is not new. The documentation format is supported by a large open source community.
| s9v: | Traceability |
|---|
It is possible to diff a documentation file with the version control system (VCS). Therefore it must be text-based.
| scf: | Accessibility |
|---|
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: | Accessibility, Traceability, 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: | Accessibility |
|---|
Full text search over all files with regular expressions shall be available from inside the editor for
- source code and
- documentation
| sed: | Sustainability |
|---|
The documentation can be opened by a normal text editor.
The documentation is easy to read and write in a text editor.
| s45: | Formatting vs Content |
|---|
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 (r9g)
- 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)
| sgt: | Redundancy, r1p |
|---|
Make it easy to automatically generate parts of documentation
- from source code
- from data
Data shall be usable
- in source code
- in documentation
| s0t: | Traceability |
|---|
Automatically generate a dependencies file that shows how documentation items are linked. Warn about missing or duplicate targets.
| s8c: | Redundancy, r8d |
|---|
Provide means to integrate into the documentation
- defines that are also usable in source code
- calculation results
Requirements on Project¶
| s10: | Traceability |
|---|
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: | Automation |
|---|
The project uses a build system.
Creation of documentation is integrated in the build system.
| s1g: | Redundancy |
|---|
Whenever something is used twice in code and documentation let it be generated from a master copy: constants, defines of structs, …
| scs: | Accessibility |
|---|
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: | Accessibility |
|---|
There is a readme document that informs, where to put and how to find which information.
| seo: | r90 |
|---|
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: | Parallelism |
|---|
Developers can work independently.
This is linked to s10. The VCS needs to enable independent development. A distributed VCS like GIT has advantages in this regard.