Date: 2023-12-19

Proposed

There are multiple locations for documentation and it's not always clear where to put documentation. We hope to clarify why and when to use one location over another. This ADR attempts to define at a high level, the relevant types of documentation and where it should be located:

• README.md
• Wiki
• Living Documents - I sense a gap in the team's documentation needs, and propose Slack's Canvas feature below
• Escalations - It has also been proposed that we track escalation events and I started the [Escalation-History] wiki page for that.

• README.md

  • Entry point for the project
  • The VRO Greeter - its not going to answer your question, but will hopefully point you in the right direction
  • Each directory of the repository presents another opportunity for a README.

• Wiki

  • Primary location for technical documentation. Targeting VRO developers, partner team's, and other teams looking to on-board with VRO.
  • We want the wiki to include information relevant to:
    • on-boarding new team members
    • providing how-to documentation and internal quick-start guides
    • we should plan to include tech specs
  • To contribute content or download a copy of the wiki, Github hosts all repositories hidden repository that via git clone [email protected]:department-of-veterans-affairs/abd-vro.wiki.git
  • A potential future consideration: The fact that we are using Github flavored Markdown opens possibility of launching the wiki as an MkDocs website, the main benefit being to improve searchability and navigation. LHDI also hosts their documentation as MkDocs static sites on the github.io domain.

• Slack Canvas Pages

  • With Slack as our primary communications platform, I want to propose that we use Slack's Canvas feature to provide the team with a space for living documents, sometimes referred to as evergreen documents. Software projects often have need for documents that easily support ongoing modification and update. This type of dynamic documentation works best for planning and design purposes and also for documenting work that that is actively in progress. Living documents need to capture and reflect the latest information, research, or developments in a particular subject matter. Over time, activity dies down and the dynamic needs of living documents become less important. In this sense, a living document can become dormant, at which time it may become an excellent candidate for the static and long-term storage of our github wiki.
  • Alternatives to Canvas include systems like Confluence, Google Docs, Sharepoint, Mediawiki, Notion and many others. Computers within the VA network blocks access to many of these. Canvas however is widely supported since Slack is embraced as a vital communication tool.

We would encourage readme.md docs throughout the abd-vro repository to direct interested parties to locate the documentation they are seeking. Introduce the use of more Slack Canvas to support the living/evergreen document requirements. As activity dies down and subject matter becomes more static, Canvas pages would graduate and become excellent candidates for the github Wiki. There is no requirement to use Canvas, since it doesn't always make sense. Nor would it be required for Canvas pages to always graduate into the wiki. Instead, this ADR is seeking to formalize the use of Canvas in support of living document requirements.