Overview

The content review portion of the GovStack publication process is intended to ensure that our various forms of documentation provide a consistent structure, style, and technical perspective. To accomplish this we have divided the publication process into two stages: Review and Read Through. While these terms can be synonymous, in this context the “Review” is a thorough review of the content and structure of the documentation while the “Read Through” is intended to be a quicker final pass through the documentation to look for any surface-level issues (misspellings, style issues, broken links, etc).

The steps that we have followed in the past include:

1. Content Completion

2. Initial Review

3. Content Updates Based on Review

4. Additional Reviews/Updates as Needed

5. Final Read Through

6. Critical Content Updates Based on Read Through

7. Content Publication

1 - Content Completion

Responsible Party: Working Group

We prefer to look at content that is considered complete, as much as possible, to ensure that we do not spend time providing feedback on things that are already known or still under development. However, it can also helpful to look over the content structure as it is being written, to ensure that it matches the expected template.

Once the content is considered complete by the working group and that content is on GitBook, the Triage Lead should inform the Technical/Product Leadership that the content is ready to review. This is often done during a Technical Committee meeting along with an overview from the working group so that the broader TC is able to provide feedback as well.

2 - Initial Review

Responsible Party: Technical/Product Leadership

Once the content is ready to review, the Technical and Product leadership team takes the lead to either review the content themselves or identify individuals within the GovStack team to do the review. As noted earlier, this review is looking at the documentation to ensure that it follows any content-specific templates, adheres to the expected content structure and organization, adequately describes overall functionality, and generally is at the level of quality we expect to publish something as part of GovStack.

At this stage feedback is generally gathered into Jira and combined into a single Epic for each content group (that is each BB Spec, Use Case, etc). Each Jira ticket should include information about the requested change along with proposed remediation options and is then assigned to the Triage or BB Tech Lead.

3 - Content Updates Based on Review

Responsible Party: Working Group/Triage Lead

As feedback is gathered into Jira, the working group can start working on changes or initiate discussions regarding the feedback.

4 - Additional Reviews/Updates as Needed

Responsible Party: WG and Leadership

As content is updated in response to the review feedback, the Jira tickets are updated and a final review is performed, just focusing on the updates. This may result in multiple rounds of feedback and updates, depending the change. Note that it can be helpful to track discussions regarding feedback directly in the Jira tickets (as comments) so that there is centralized location to follow decisions regarding any updates.

5 - Final Read Through

Responsible Party: Product Leadership

Once the review process is complete the Working Group and Tech/Product Leadership teams are indicating that the content is ready to publish. We now do a final read through of the content, performed by representatives of the GovStack partners who were not involved with the review process (as much as possible). The goal for this read through is to look for any glaring issues with the content, not to perform a deep technical review. Likewise, this is also an opportunity to ensure that the partners are all familiar with the new content.

6 - Critical Content Updates Based on Read Through

Responsible Party: Working Group/Triage Lead

Feedback from the read through is marked as either Required or Recommended, with only Required changes being implemented prior to publication. Both types of feedback are entered into Jira and follow the same process as described in step 3, with Recommended items being recorded but not assigned to the current release.

7 - Content Publication

Responsible Party: Product Leadership

Once all Required updates have been completed and validated, the content is ready to be published. This is normally done along with any other content being included in the broader GovStack publication plan, though individual publications can be done as well. For details on the technical publication process, see GitBook/GitHub Publication Process.