As a VSP team member, I need to be able to write documentation that is consistent and meets VSP's standards, so that VFS team members easily use and understand platform docs to build and iterate on VFSs.
Problem Statement
VSP currently has no standards for writing documentation. This affects docs in a wide range of ways, from varying formatting of code examples to team members talking past each other while referring to "feature toggles," "feature flags," "feature flippers," "Flipper," (due to no word list), and more.
How might we begin to set a shared understanding of how to write documentation, so that our own docs can be more consistent and so that we have a resource to point VFS teams to when needed?
Hypothesis or Bet
If we create a documentation style guide, then VSP will have more consistent and professional documentation.
If we create a documentation style guide including a word list, then VSP and VFS teams will use more consistent language for shared tools and processes (resulting in decreased confusion and increased findability of relevant resources).
OKR
VSP OKR — O1: Teams have efficient experiences using the platform to build impactful products for Veterans, where their expectations are exceeded.
Success metrics
Qualitative data from docs contributors: is the style guide useful?
Pageviews (MVP - clicks from documentation homepage)
Total number of words in word list
Number of words in word list with conflicting definitions or terms (low)
Number of VSP support requests that include link to documentation style guide (>5 per month)
[analytics of docs usage and feedback to come in future documentation tool]
We will know we're done when...
[ ] Style guide is in va.gov-team repo
[ ] Style guide is linked from docs homepage
[ ] Style guide is socialized to VSP teams
[ ] Word list is socialized to VFS teams
[ ] Known future additions to style guide are captured in backlog
Additional Details/Notes (optional)
The approach for the style guide at this time is to have a resource that we use as a documentation team, that VSP team members are strongly encouraged to use, and that VFS team members are optionally able to use. We do not anticipate creating a process for retroactively editing content across all docs to conform to the style guide.
Artifacts
Documentation site product outline (the documentation style guide is a feature of the documentation site product)
vbellissimo
commented
2 years ago
High Level User Story/ies
As a VSP team member, I need to be able to write documentation that is consistent and meets VSP's standards, so that VFS team members easily use and understand platform docs to build and iterate on VFSs.
Problem Statement
VSP currently has no standards for writing documentation. This affects docs in a wide range of ways, from varying formatting of code examples to team members talking past each other while referring to "feature toggles," "feature flags," "feature flippers," "Flipper," (due to no word list), and more.
How might we begin to set a shared understanding of how to write documentation, so that our own docs can be more consistent and so that we have a resource to point VFS teams to when needed?
Hypothesis or Bet
OKR
VSP OKR — O1: Teams have efficient experiences using the platform to build impactful products for Veterans, where their expectations are exceeded.
Success metrics
We will know we're done when...
va.gov-teamrepoAdditional Details/Notes (optional)
The approach for the style guide at this time is to have a resource that we use as a documentation team, that VSP team members are strongly encouraged to use, and that VFS team members are optionally able to use. We do not anticipate creating a process for retroactively editing content across all docs to conform to the style guide.
Artifacts
Communication