Once a release of the specifications is made, we hope to receive feedback on its content and it will be handled using the process below.
How a reader gives feedback
A reader of the specification will be browsing the specifications at govstack.gitbook.io and may identify a page that requires feedback.
The main navigation menu of the specification website has a “Give Feedback” option:
The user clicks the Give Feedback menu and they are automatically taken to a short form where they can enter their contact details and describe their feedback. The form automatically obtains a link to the actual page in the specifications that they were reading at the time but the reader can alter this if needed.
Upon submission, the reader is thanked and the form automatically creates a Jira issue for us to track the feedback in the building project project associated with the page. The reader is given a link to the issue as a hook to hopefully encourage some readers to continue to engage with the feedback.
In the days following submission of feedback, the person giving feedback should receive thanks from the Building Block Lead associated with the content they gave feedback on, either through the Jira issue they were linked to or via email.
How GovStack handles the feedback given.
Role Responsible: Building Block Lead
How often? At least once per week
Giving feedback on the specifications may be the first active engagement and contribution a person makes with the GovStack project and the building blocks it describes. We have a golden opportunity to make the experience one that will lead to some engaging and contributing more and more.
The Building Block Lead, or delegate, should review their Jira project for any new issues. Those created by the Feedback form always have a title beginning with “Feedback on specifications, submitted by” which helps with searching.
For each new issue:
Consider if it is “spam” - this is always a possibility and you may close the issue if it is. Add a comment saying it is spam.
Thank the person giving the feedback
Add a short comment to the issue saying thank you and give some indication of how the feedback will be reviewed
Drop an email to the person giving feedback. To obtain their email address, copy the code in the issue title and use base64decode.com to decode it to an email address. We encode the email addresses people supply so that they are not easily scraped by spam engines. We do, however, warn those submitting feedback that the email address they supply will be share with GovStack community members.
An example email text might be
Thank you for your feedback, we really appreciate your thoughts on this. You will see that we are tracking your feedback on our systems at xxxxxxxxx and we would very much like to give you credit for your contribution, unless you prefer otherwise? Are there any other ways in which we could collaborate? I would be happy to explain more how we developed the materials so far and how we work with many people to ensure they are relevant and impactful.
If you notice multiple items of feedback from the same person, you might want to consider inviting them to our Jira instance and then making them the reporter of the issue, rather than the default “GovStack Bot”. This is a key way in which we can draw more people into the project over time and then support further work on GovStack.
Process the issue and any change needed to the specifications
When an issue is finally closed, especially if it is closed with their comments added to the specification, make sure to say thank you once again. If they are engaging in the Jira issue, then that would be the right place, otherwise use their email address.
Supporting Building Block leads during a post-publication rush
In the weeks following a release of the specifications, it is possible that there would be a large influx of feedback that might overwhelm Building Block Leads. To assist them in their responsibilities, we will have a response team in place for four weeks following publication.
The response team will assist building block leads by:
Reviewing all incoming Jira issue feedback for spam and closing it
Review Jira issues and assess if they have been placed in the correct project, moving if necessary
Move any feedback issues that are not really related to the content of the specifications into the product-committee project and respond to them as required
Where an issue has a clear change that can be made, creating a change request and noting it in the Jira issue with a comment
Assigning issues to the Building Block Lead
Checking in with the Building Block Lead and ensuring they are able to respond with thanks to the person giving feedback