UNCLASSIFIED - NO CUI

Skip to content

Charter, Documentation Locations

Christopher McGrath requested to merge BBOI-382_charter_doc_strategy into master

Follow this link to see the draft:
https://repo1.dso.mil/platform-one/big-bang/bigbang/-/blob/BBOI-382_charter_doc_strategy/charter/DocumentationLocations.md

Purpose of the Merge Request: Drive Discussion on Documentation Strategy, Conventions, Requirements, Storage Locations, Identification of different types.

Problem Statement:

  • There are different types of documentation for different use cases:
    • Docs for folks just trying to wrap their heads around it / understand an overview what's available and how mature certain components are. Architecture + Component Maturity Matrix (Component, IB Image Exists+works, Demo-able, Stable, Maturity of Docs, Maturity of Automation)
    • Quick Start Demo user doc (a noob should be able to easily deploy BB in a non prod demo setup)
      • this could have its own non prod architecture diagram to help people wrap their heads around it.
      • this could have video(s) where people can watch start to finish instead of do
    • How to Install BigBang in a a production like manner, Gotchas, pre reqs, step by step instructions for those who are
      • There's also generic directions + Cloud/Env specific directions
    • Package Post Install Configuration Docs (Rob Kernick made progress on game plan for this)
    • BB Developer/Contributor Documentation
    • Internet Connected vs Internet Disconnected should be stored in different repositories as they'll likely have different methodologies, and different docs. (I know the future state is to support airgap only even for internet connected deployments, but we won't be there anytime soon and we should probably walk before we run. The whole XP thing of code for today not tomorrow)
  • Deployment Documentation should be lengthy and in depth to be useful
  • I suspect it'd be good to have different documentation owners for different types of docs.
    • we probably want documentation owners to be able to approve and merge documentation MRs
  • We should consider not having a 1 size fits all solution for docs / come up with rules for different types of documentation.
    • Maybe developer/contributor documentation doesn't need to be versioned? / only the latest version matter?
    • Package docs could go in Hugo
    • Deployment docs might not need to be in Hugo
    • Maybe different documentation should go in different repos (this will help give scope to documentation, and make it so that we can be more liberal/less rigorous with gitlab rights to documentation repos.)
  • We have documentation everywhere: It'd be nice if the BB charter officially specified where the source of truth for different types of documentation should exist.

I'll use this Charter MR to define a documentation strategy with my proposed answers to these questions, and use that as a starting point to drive discussion.

Edited by Christopher McGrath

Merge request reports