Sunday, 19 June 2016

How to Scale Documentation, Part 6

Ok, I've got me a web server and an efficient, scalable automated build.  How do I get feedback?

No chit-chat or flim-flam, straight down to business.  I like it.  How's that for feedback?


That's payback for me mocking the Star Wars joke at the end of Part 5, isn't it?

Yes, but I'm not one to hold a grudge so let's leave it there and talk about Feedback.


That would be awesome.....


Good.  Feedback is the part of the cycle where work for the writer enters the pipeline.  This could be things like change requests and bug reports, all of which come under the "common" understanding of the word Feedback. However, in terms of the documentation cycle of Input > Delivery > Feedback, Feedback can also mean legislative changes, statutory changes, paid enhancements, and anything else that enters the pipeline and requires you to make an addition or change to the documentation.


But you said in Part 5 that having the documentation on a web server allowed you to gather feedback.  How does that cover all of those Feedback types?

It doesn't.  But real live customer feedback and usage data is tough to get without a central help site where you can track a user's movements through the documentation.  The other Feedback - legislative/statutory changes, paid enhancements, that sort of thing - will normally be tracked by Product Managers and Account Managers, and the Product Owner will feed them into the backlog in priority order.

This gives us 2 types of Feedback:

  • Product-focused - Anything that will require a change to the product (legislative/statutory changes, enhancements, software bugs, application maintenance, etc) and therefore a change to the documentation.
  • Documentation-focused - Anything that relates to the documentation itself, such as spelling/grammar errors, lack of clarity, omissions, requests for additional documentation, etc.
Product-focused feedback is something that requires a change to the documentation to accommodate work done by development.  We'll leave that feedback to Support and Product Managers and only look at the documentation-focused feedback, as this is the feedback that a writer should be responsible for tracking and responding to.  A lot of this feedback will come from the documentation on your web server.


I understand that distinction, but how do you get the feedback from the website? And how can you scale it?

Both fair questions.  As far as getting feedback, you've got several options, such as:

  • Google Analytics, which will supply you with more data than you thought possible about who, when and how people are using your site;
  • MadCap Pulse, if you're using MadCap Flare to create your documentation, which will provide analytics and also the ability for users to provide topic ratings and feedback;
  • Wufoo (or other such services), which allows you to create forms and surveys that you can embed in you site;
  • Comments, if you're using a wiki like Confluence, which allow users to give you any kind of feedback they want.
Of course, you can embed your own feedback mechanisms in to your web site if you wish; your choices are limited only by the usual restraints of price and time. 


I'll look into those.  Don't they scale already though?

Yes, they do.  Any of those options will work whether you get 100 visitors a week or a 100,000 a day.  When it comes to scaling your feedback processes, you need to focus on how you deal with that feedback.

Ideally, you will:

  1. Triage the feedback as it comes in (or at least triage it in bulk a couple of times a day);
  2. Delete the spam/junk feedback;
  3. Answer any positive feedback with some form of thank you;
  4. Answer all negative feedback, regardless of whether you can do anything or not (because an acknowledgement is often surprisingly good at diffusing unhappiness, even if you can't actually fix the problem);
  5. Add all feedback that requires you to make a change to the backlog in priority order.
Bearing in mind that you can't scale past a bottleneck, there are several areas you need to make sure you can scale;
  1.  An alert system should be in place so that at least it's obvious to the whole team when feedback has been received, even if you don't want a popup notification on your screen every time feedback arrives. 
  2. Keep a rota of who's responsible for dealing with feedback in any given time period;
  3. Make sure that multiple people have the authority and permissions to access the feedback and reply to it;
  4. Make sure that the same people have the authority and permissions to add things to the backlog;
  5. Provide templates for responses to different types of feedback.  These shouldn't be "robo-replies" because people don't like getting a pro forma that obviously no-one has put any thought into, but enough of a skeleton to include contact information, company header, standardised greetings and sign off, that sort of thing;
  6. Decide on the prioritisation order of feedback.  This could be severity, number of users affected, speed/complexity of fixing, or anything else that's most important to you.  This order should be used by everyone when prioritising the feedback that's added to the backlog.
Once all this is done then you can use your automation of the build and deployment to fix documentation issues and make the new version live on the web server on the same day.  This is the documentation equivalent of continuous integration, and it is the ultimate aim of your feedback system - find a problem in the documentation, fix it, build and deploy the new documentation.  All done efficiently and scalably.


That sounds awesome!

Yes, it is :-)


But...is it really that simple?

Conceptually, yes.  Practically? Maybe, maybe not.  It depends on your company culture towards documentation, customer satisfaction, continuous integration (which some people see as a risk), and so on.  But this kind of system is eminently possible.



Hmm.  There's a lot to think about there.

Yes there is.  But the bones of everything you need to scale your documentation is in this and the 5 previous posts on the subject.  I hope they've helped.
 


They sure have.  I was expecting a bit more on Feedback though.... 

If you bear in mind the principles we've covered in the previous posts - the removal of unnecessary steps and bottlenecks, automation and cutting out repeated decision making - you should be able to see that you can apply them to the Feedback processes.  I reckon you know enough to be able to take these principles and apply them to your situation without me holding your hand any more.


Bit scary, but nothing ventured, nothing gained.  I'm going for it!  Thanks for talking to me about this.

My pleasure, and I'm sure you'll succeed.  Good luck!