Project

General

Profile

Feature #3032

Clean up dev-manual structure

Added by Eric Irrgang 3 months ago. Updated 3 months ago.

Status:
New
Priority:
Normal
Assignee:
-
Category:
documentation
Target version:
Difficulty:
simple
Close

Description

There are various "to do"s noted in RST comments but I don't know any Redmine Issues yet.

Style guildelines and developer tools are both categories of documentation that are indecisively organized right now, creating both redundancy and obscurity. I think in both cases, we can probably put the tool or style documentation closer to the other documentation that it is related to and enforce that, if there are Tools or Style high-level sections, they should be maximally terse sets of links referring to other documentation sections. For instance, much of the Tools could be moved to one the more introductory documents, essentially saying "before you begin, be aware of these tools referenced in later sections... you may want to install them now."

History

#1 Updated by Eric Irrgang 3 months ago

One thing to keep in mind is that Sphinx and ReStructuredText documentation makes the most navigable documentation when the documentation is inherently structured serially and (optionally) hierarchically. This is reflected in that each file has a primary point of entry and a place in a document tree. Adhering to flat web-like documentation leads to misleading auto-generated tables of contents, inconsistent navigation side-bars, and redundancy.

#2 Updated by Eric Irrgang 3 months ago

Eric Irrgang wrote:

One thing to keep in mind is that Sphinx and ReStructuredText documentation makes the most navigable documentation when the documentation is inherently structured serially and (optionally) hierarchically. This is reflected in that each file has a primary point of entry and a place in a document tree. Adhering to flat web-like documentation leads to misleading auto-generated tables of contents, inconsistent navigation side-bars, and redundancy.

Make tools.rst a stub

Move owned documents to better homes and merge original content to other authoritative sources.
From tools.rst

- move doxygen to documentation-generation
- move change-management to contribute
- move jenkins to releng? build-system?
- move releng to build-system, contribute, or top level
- move gmxtree to overview
- move uncrustify to contribute
- move testutils to build-system or top level
- move physical validation to testutils or top level
- merge redundant "Change management" section to existing change-management document
- merge redundant "Build System" section to existing Build System document
- merge "code formatting and style" section with contribute.rst, its children, and other existing documents

Make style.rst a stub

Move owned documents to better homes and merge original content to other authoritative sources.
From style.rst

- move formatting to contribute
- move includestyle to contribute
- move naming to contribute
- move language-features to contribute
- move report style to change-management
- move commit style to change-management
- move error-handling to contribute
- update list-of-links

This alone will not eliminate all of the redundancy, but will hopeful direct traffic better and help clarify the remaining redundancies.

Also available in: Atom PDF