Document specification for software package documentation structure

[strogonoff]

Open Project framework has very simple requirements for a set of software documentation. This specification should be included in the docs. Drafting it here:

• Software docs is a directory with files in a format understood by Jekyll (we use AsciiDoc with requisite plugin).
• A document with special name “navigation” must exist alongside those files. The document should be empty but contain YAML frontmatter with ToC-like description of the structure in which project site would present the docs to the reader.
• The directory containing the documentation should be part of a Git repo. It is expected that Git tags are used to version the software being documented. The framework will build docs for multiple versions of software based on those tags, and allow the reader to switch to the docs for the version they’re using (feature in the works).

[ronaldtse]

@strogonoff it sounds like you need a specification to describe this 👍

Here are examples of our own specifications:

• https://github.com/riboseinc/nereon-syntax
• https://github.com/riboseinc/ros-encrypted-tokens

[strogonoff]

Was thinking along the same lines. I expect implementing Metanorma-based build for specs in Open Project framework would also uncover a few ways to improve how software docs are treated.

On Aug 3, 2018, at 6:40 AM, Ronald Tse notifications@github.com wrote:

@strogonoff https://github.com/strogonoff it sounds like you need a specification to describe this 👍

Here are examples of our own specifications:

https://github.com/riboseinc/nereon-syntax https://github.com/riboseinc/nereon-syntax https://github.com/riboseinc/ros-encrypted-tokens https://github.com/riboseinc/ros-encrypted-tokens — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/riboseinc/jekyll-theme-open-project/issues/24#issuecomment-410100548, or mute the thread https://github.com/notifications/unsubscribe-auth/AAR4X80asRyUwDLTTO8alqN3dweZQ1Aiks5uM43TgaJpZM4VsrMd.

[ronaldtse]

Indeed! We do want to improve Metanorma for various use cases.