5 Things Writers Need From Developers

Developers don't like writing documentation in the same way that cats don't like having a bath. There might be the odd breed of cat that likes a bath, just like there is the odd developer who likes writing documentation, but generally cats and developers are quite predictable when it comes to baths and documentation.

But people like being able to get necessary-but-onerous jobs done with the minimum of effort, time and thought, and developers are no different.  So here is a list of 5 things writers want from developers. 
 

Clarity 

Don't provide a steam of consciousness brain dump about the work item you're documenting.  List things in some kind of order.

Accuracy

Can't remember why you added a radio button to the UI?  Don't make up an answer.  When you're not sure, tell us you're not sure.  If you know the name of someone who might know, give us that name.  We'll do some legwork for you.  But don't ever make stuff up.  

Timeliness

Not just about when you get the docs to us, but when you write them.  Yeah, the next piece of work you've been looking forward to is much more interesting that documentation, but tough luck.  Your memory is fallible and you will forget details of the work you've done.  So either document as you go, or at least document before you move on to the next piece of work.  It will save you and the writer a lot of pain later on as they have to spend time interrogating you and your terrible memory.

Completeness

Also known as 5WH: What, When, Who, Where, Why and How.  WHAT was done, WHEN was it done, WHO did it, WHERE was it done, WHY was it done, HOW was it done.  If you take nothing else away from here, remember 5WH.  

Consistency 

Provide the same information every time in the same place.  Create a template.  Ask the writer to create a template for you.  Get every developer to use the same template and save it in the same place - a new Confluence page in the Release space for every work item, in the comments of the JIRA item, in a dedicated Slack channel for that release, in a README for every GitHub pull request, wherever works for the team.  Then do the same thing every time.


Some notes on the above:

• There are pieces of information that it's just common sense to include, like the names of people who worked on something and the numbers of linked work items.  Forgetting to include these makes you look anything from unprofessional to incompetent.

• There are pieces of information that the non-writer may not think need to be included.  Ask the writer if they want that information included.  This is one of the ways a template really helps.

• Writers hate it when their work can be called into question, especially if it's because a developer has fed them some made-up information.  Reputation is important to writers, so don't make them look bad at their job. (This is a pretty good rule of thumb for all interactions in your life.)

• Being part of the "too cool for school" culture that mocks people, especially developers, who write documentation is boring, unprofessional and frankly pathetic.  It's part of the "bro culture" that everyone hates (apart from bros, obviously).  It should be embarrassing to you if you get your kicks from ripping on other professionals in your office.  Stop it.  If you're reading this then hopefully you're not that kind of developer.  Spread the professionalism around your office as required.

• Developers who write good docs are normally the better developers in the office.  Writing good documentation requires you to be able to step into someone else's shoes, as does writing good software.  The most respected (and best paid) developers I've worked with over my career have significantly overlapped with the developers who write good documentation. 

• When all's said and done, developers need to communicate what they've done, whether they want to or not.  Learn how, become a better developer, become a better professional.