User Guide as a Living Document - how to keep it current/rich/relevant?

Tags: #<Tag:0x00007f1af7b8e1b0>

This topic was born on Slack and seems to have outgrown it. We’re talking about the process for editing the user guide and making sure that user guide editors in all languages can benefit from each others work. Copied here are the slack posts that got things going, starting with a thread from Emily Rogers:

Here’s a suggestion for how we update the User Guide as a group. This is an interim measure until we can get multiple user accounts for Gitbooks, as we currently have to share editing under a single login.
(See here for background, including a video on how to update the guide
I would also suggest the process below is not necessary for fixing small typos, grammatical errors and simple clarification of text.

Recommended Process for bigger changes:

  1. I see a change that needs to be made to the User Guide
  2. I log in to Gitbooks and make the change, naming the draft logically
  3. I share the draft here with a simple naming convention
  4. Comments and discussion take place in a thread, if necessary
  5. At least three of us review the change in Gitbooks and come back here to give it a ‘thumbs up’
  6. Once we have three (?) thumbs up, the change is merged (made live)

I’ve made a sample change and will post an example below for us to practice on! (edited)

Emily Rogers [11:53 PM]
REVIEW EDIT: Edited Value description in Product section
I’ve made a small change to clarify the way we describe Value in the Product section of the User guide. Everyone OK with this?
Discussion in Thread.
Thumbs up to agree.

myriam [12:19 AM]
That sounds great @Emily Rogers! In Gitbooks I’m driven to the main page but if I activate “view changes” then I see in orange the menus that I need to go to to see the changes, it looks pretty straightforward :slightly_smiling_face:

LaurieWayne [4:55 AM]
I woke up thinking about the user guide too today and how information seems to be flowing (or could flow) from Slack to the guide. What if we treated updates to the guide kind of like we treat updates to our code, but instead of bugs we have updates, and the work of updating is documented, shared, trackable, and prioritized? I think it deserves the same attention and disciplines as the code base. An example of how this could work using the tools and processes already in place (as I understand them):

  1. Customer Support person has a question or scenario that they don’t see handled in the user guide, so they post their question in #customer-service. This happens now.
  2. Lots of people respond with different options. Knowledge is captured! Ha! Gotcha!
  3. When best answer is determined now, it just gets lost on Slack, but we can bring it into the light of day: a guide update request is issued in Github (this looks basically like a bug report or pull request – but the knowledge that was captured in all those slack threads goes into the update request.
  4. As happens now with pull requests, the update request is labeled (with things like “good first update”, the user guide section it goes in, and possibly how likely it is that a user will need this information) and given a severity (priority)
  5. You want to update the user guide? GREAT! You claim an update request, make the changes based on the captured information, and flag the update request for review.
  6. Your update is reviewed, merges your update, and the request is closed in Github.

Three things I don’t understand about the code update process (which I am proposing is paralleled by the guide update process): who does the reviewing of a code/guide change, who does the actual merging into the code/guide, and what is the role of the train driver in the process? (edited)

rachel [5:26 AM]
I would suggest you a workflow for new features being added to the guide and another one for updates (but maybe this is what Emily was thinking with “small changes”).
While new addition can be reviewed before merging, I would allow updates to be merged directly. Updates needs to happen regularly and must be done by the support team who needs it. When you answer a user you cannot wait for your submission to be reviewed (no matter the size). So what will happen in the long term (and I’ve seen this in other projects) is that the support team will answer directly in the email to the user and will save the user guide updates for “later”. Later which in most cases turns into never because documentation is not fun and nobody wants to do it especially if there is a lot to catch up. I strongly believe that any support team should always answer with the user guide if the answer needs an explanation (and do updates if there are things missing).

For new features, this is quite different because you will need the product owner to warn you a new feature will be released and you will need input from the product owner on how it works. It is then a longer time frame that can benefit from a more detailed review.

That does not mean you shouldn’t review what was added in updates. But I think this can be done by a simple notification here on slack.

This is quite different from the process we use to improve our code. I will answer in a thread about how things work currently.

LaurieWayne [5:39 AM]
So @rachel can you define what would be an update as opposed to a new addition? I think for updates (small changes) you are suggesting that the process is:

  1. Thing is not in user guide, gets asked and explained in Slack (#customer-service?) or customer supporter already knows answer/notices it is not in guide and needs to be
  2. Customer supporter updates user guide with this new information
  3. Customer supporter answers user question (if there was one) by pointing to the user guide update that they just did
  4. Customer supporter notes the update in the #user-guide channel
    ? (edited)

tschumilas [1:47 PM]
I agree with Rachel that the best time to make additions/changes, elaborations to the user guide, is when a user has requested help with something. The person giving support checks what the user guide says (at least I always do) and then elaborates to the user, OR corrects the guide, OR makes it more clear… So at that moment, the issue is clear in the mind of the support person, and this is the perfect time to suggest a change to the guide. I think the question is - do other people need to review the change and how can that work in a timely fashion. Maybe it depends on the scope of the change?

Emily Rogers [4:36 PM]
OK, so I’m getting the sense that there are a few different types of User Guide Update, and that they each need a different approach. Would it be something like this?

  1. You find a small typo, spelling or grammatical error, wrong word, poorly written sentence or simple problem that needs a tidy up = JUST MERGE IT!
  2. A support issue triggers the need for an edit that clarifies the user experience, or explains something that is not currently well covered in the UG = Make Change, Review/discuss/get agreement in Slack… then MERGE IT!
  3. A new feature is introduced to OFN and needs a relevant section created in the UG = Incorporate new UG content into the code release process, with full documentation of edits and review etc… then MERGE IT!

The process I suggested above would be appropriate in Scenario 2. What @LaurieWayne has described would be Scenario 3. Thoughts?

LaurieWayne [5:14 PM]
replied to a thread:

Nice @Emily Rogers - thank you! I am working on a flowchart for decision making about when to MERGE IT! - I would say I am actually more looking at Scenario 2, which is when something is not well covered, which can manifest as a question in #customer-service - I am hoping to come up with a process for capturing those conversations and making sure we are getting that information in the user guide, or in a wiki or somewhere beyond Slack, which is great for conversations but is not a great repository.

I am considering the possibility that the people coming up with and solving the problems in customer-service are realistically not going to be instantly editing the user guide (and they may not be the right people to be doing it from either a skill, time, or motivation perspective). So if my favorite thing to do is update the user guide, or I just want to make sure a conversation/solution is captured because it should be in the user guide, how do I proceed? If my favorite thing is to do tech support and I am maxxed out on helping users do the things they need to do (while simultaneously learning OFN from more experienced colleagues in #customer-service) how do I proceed and make sure the very valuable conversations and examples make their way to the user guide if I am not able to do it?

If my instance tracks problems and solutions in Trello or Zendesk or elsewhere, how do we capture that information and make sure it finds its way into the user guide?

Scenario 3 seems way more sequential and under control than some of the stuff that’s happening in #customer-service, which is directly driven by users having a problem that impacts their ability to do business or their comfort/confidence with OFN.

I also don’t at all know where to go with it, but how do we keep the English user guide synchronized or at least keep important information, video demos, and such included in non-English versions of the user guide? (and how do we make sure the amazing stuff that non-English user guide writers come up with makes its way to the English one?)

Emily Rogers [9:12 PM]
@LaurieWayne yeh these are good points. I had been coming at Scenario 2 from my own perspective as a ‘contenty’ person who would love to get stuck into the User Guide as soon as a problem is identified! Is it viable to have a global User Guide editor to coordinate everyone’s changes? That way anyone who is inclined to make an edit can go ahead and make it and request the the UG editor to perform the final MERGE. Also, could it be a simple use of tags whereby anything that warrants a UG update is tagged in the relevant Slack conversation #UGedit and the editor can then periodically pick these up and implement.

As for the non-English versions - yes ouch - that’s a big question and I’m not fully across how they are maintained and created now. Though Gitbooks does let you review all changes, so the ‘other language’ UG owners might just need to do a periodic review and update.



Thanks for bringing us in here @lauriewayne1!

To move forward, it looks like we have three main tasks:

1. User Guide Update Flowchart
Create and agree on a flow chart for decision making and sign off of edits to the User Guide under two different scenarios:
a) A new feature has been created on OFN and needs to be reflected in the UG
b) The UG is not clear/correct and needs to be changed or improved

2. Feed User Guide Changes from Customer Support
Figure out how to identify & capture changes that should be made to the UG that manifest via Customer Support and through conversations in the Slack #customer-service channel, email, Trello, Zendesk etc - and feed these into the UG update process.

3. Manage Multiple Language Versions
Figure out how to manage UG edits so that they flow through to other language guides if necessary.

I would also like to add a 4th task, which is to agree on an interim updating process while the above tasks are being worked through. If we are aware of changes that need to be made, and resources are available to make them, we shouldn’t hold things up on the way to designing the ‘ideal’ solution. So…

4. Quickly Agree on an Interim Update Process
Prioritise agreement on who can make, review and merge necessary changes right now.

Shall we address these 4 issues separately so as to stay focussed?



Yes that is bang-on, @EmilyRogers! I am (supposedly) working on #1 and could I ask that we expand #2 to include other places that changes could come from (for example customer support mechanisms like email, Trello, and Zendesk as well as Slack?



Good call, I’ll update point 2 above.