New Guidance on Creating Documentation Organization Hierarchy

[riverma]

Purpose

• New documentation reference architecture for helping folks organize their project documentation using a standard approach
• Why a standard hierarchy? To help reduce the time it takes to find what you need within projects' documentation, especially between projects in the same science domain.

Proposed Changes

• [ADD] Reference architecture (markdown) diagram for documentation hierarchy
• [CHANGE] Added wording to blank existing reference architecture file

Issues

• [Improve Existing Best Practice Guide]: Documentation Organization Ref Architecture #29

Testing

• See this file for the proposed documentation hierarchy: https://github.com/NASA-AMMOS/slim/pull/30/files#diff-418170666bb25e2f47cc5960c5df52f585d3233c186bb678f48d1862db3d00cc
• Tested locally and renders fine using RETYPE

[jpl-jengelke]

Thanks @riverma. On review, here are my comments:

• Is this duplicating the Use Case diagram? Is that necessary? My thoughts were that maybe this section would contain a flow chart or UML to discuss the creation process rather than reviewing implementation.
• What parts are auto-generated, and is it necessary here? The reason I ask that is after we talked last I understood the architecture would be sort of high-level planning or flow oriented.
• I may be thinking of things from the perspective of application design, so my comments could be out of context or don't translate well to the documentation problem space.

[riverma]

Great questions @jpl-jengelke - let me see if I can answer them.

Thanks @riverma. On review, here are my comments:

• Is this duplicating the Use Case diagram? Is that necessary? My thoughts were that maybe this section would contain a flow chart or UML to discuss the creation process rather than reviewing implementation.

The use of markmap.js here is purely out of need, and not to be mistaken for creating another use case diagram. I was looking for a way to visualize a hierarchy, and realized markmap would support that well.

That being said, you've got me thinking whether people may be confused by the style of this diagram. I think Mermaid supports hierarchy graphs so let me see if that renders well for this kind of graph.

• What parts are auto-generated, and is it necessary here? The reason I ask that is after we talked last I understood the architecture would be sort of high-level planning or flow oriented.

Auto-generation would be a good idea, but I don't think for this section. You're right that the architecture section is more a referential planning artifact. I'm thinking that we could have starter kits that auto-generate this reference architecture (hierarchy) for various documentation host providers like: Confluence, GitBook, ReadTheDocs, etc.

• I may be thinking of things from the perspective of application design, so my comments could be out of context or don't translate well to the documentation problem space.

These are good questions - no problem!

[riverma]

This file showcases the current proposed documentation hierarchy: https://github.com/NASA-AMMOS/slim/pull/30/files#diff-418170666bb25e2f47cc5960c5df52f585d3233c186bb678f48d1862db3d00cc

Please share your comments / review this - thanks!