Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

New Guidance on Creating Documentation Organization Hierarchy #30

Closed
wants to merge 4 commits into from

Conversation

riverma
Copy link
Collaborator

@riverma riverma commented May 26, 2022

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

Testing

Screen Shot 2022-05-26 at 3 46 07 PM

Copy link
Contributor

@jpl-jengelke jpl-jengelke left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Collaborator Author

riverma commented May 27, 2022

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 riverma self-assigned this May 27, 2022
@riverma
Copy link
Collaborator Author

riverma commented Sep 1, 2022

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!

@riverma riverma changed the title New reference archi for describing doc hierarchies New Guidance on Creating Documentation Organization Hierarchy Sep 1, 2022
@riverma riverma added information sharing Process improvements involving documentation, training, guides, communication, etc and removed documentation labels Nov 1, 2022
@riverma
Copy link
Collaborator Author

riverma commented Aug 30, 2024

Closing in place of #149

@riverma riverma closed this Aug 30, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
information sharing Process improvements involving documentation, training, guides, communication, etc
Projects
None yet
Development

Successfully merging this pull request may close these issues.

[Improve Existing Best Practice Guide]: Documentation Organization Ref Architecture
2 participants