Documentation. Documentation? Documentation!

by Steve Endow

How do you create your documentation?  

When do you create your documentation?

Who in your organization creates your documentation?  Who doesn't?

Does anybody actually read your documentation?  How do you know?

Do you specifically budget for documentation in your projects?  How much?

Are your customers reluctant to pay for documentation?

Can your documentation keep up with your software releases?  Do you maintain detailed release notes?

Do you methodically and consistently update your documentation over time?  

Update:  (based on a response from Erik Hougaard on Twitter)

Do you create instructional videos or video tutorials as part of your documentation?  If so, how do you consistently record, edit, store, publish, and index such videos?  Do you have public and private (e.g. customer specific) videos?  If so, how do you handle publishing videos for those different audiences?

By now I'm sure you are excited beyond belief, as there are few topics more glamorous than "documentation".  

Is it read?

Over the last 20 years, I've worked with over 700 customers.  I've documented business processes, business procedures, ERP training guides, user manuals, customization specifications, integration designs, data mappings, installation guides, and software user manuals.

After all of this experience, I'd humbly submit that I'm fairly good at writing documentation.  I've been using a customized MS Word template for my documentation for over 20 years.  That Word template has worked well for me all these years, and it has been a better solution than anything else I've seen used at my customers. 

Over the years I've also made a few observations about documentation.

My assessment is that most documentation is never read.  Especially process and procedure documentation.  In my experience, the customer requests it, spends a lot of money having it written, and it's almost never read or updated again.  Customer-specific training manuals probably take second place.  Detailed guides are written, users become familiar with the software, the docs collect dust, and by the time a new employee is hired and needs the guides, the docs are obsolete.

The last 13 years, I've sold and supported ISV software for Microsoft Dynamics GP, and more recently for Dynamics 365 Business Central.  Based on my experience in this role, my observation is that installation guides and software manuals seem to get the most attention of all of the documentation I've written.  Amazingly, some customers actually read installation guides and user manuals.

Unfortunately, I don't have any data on how many customers read my product documentation (foreshadowing).  I'm guessing it's around 10%, but perhaps it's as high as 20%, at best.  Dynamics Partners and Customers routinely request a support call to walk through the installation process instead of reading the installation instructions in the documentation.  And when it comes to configuration issues and error messages, very few partners and customers even read the information on an error message or dialog, let alone check the documentation, before submitting a support ticket.

How do you document?

If my estimate of 10-20% utilization is even remotely accurate, I would argue that this metric dictates how I should create and maintain my documentation.

If relatively few partners and customers are reading a PDF, should I spend money on a commercial documentation solution?  Do I really need a fancy documentation publishing "pipeline"?  Would the additional cost and effort of online documentation be justified?  

Should I spend many precious hours on an elaborate documentation process that creates arguably "better" documentation?

How valuable is expensive, beautiful, feature rich documentation if only 20% of users ever use it?  Will such fancy documentation be utilized any more than a basic PDF? 

And if it is more complex to create and maintain, and if complexity means that fewer employees can update and maintain the documentation, thus creating a bottleneck for documentation, can that additional cost and burden be justified?

If I use a simple Word documentation template that anyone in my company can easily use with zero additional training, presumably that simplicity has a value of its own?

At the moment, I can only guess how many customers read my PDF documentation.  One potential benefit of web-based documentation might be telemetry and metrics.  If web-based docs allow me to easily see how many users utilize the documentation, which pages are viewed, and which are not, that could be valuable.  But if that telemetry costs thousands of dollars and results in complexity that limits the number of employees who can maintain our documentation, is that trade off worth the benefit?  

Fancy Tools!

"You should use this free open source documentation platform that depends on these other libraries that read modified Markdown language, which then gets checked into into GitHub, where a pipeline runs to generate static web pages that are then published to a web site.  It's the best!"

No.  Nope.  Absolutely not.  

I want a brand new junior consultant to be able to quickly and easily create and update documentation for a PTE, a custom report, or an integration field mapping.  I want my developer to be able to quickly update release notes, or a non-technical senior consultant to emphasize a valuable application feature in our documentation.  If I need train employees to use Markdown and a "pipeline" to create or update documentation, that's a non-starter.

"You should use this super fancy commercial documentation platform that has incredible functionality!  It's the best!"  Yes, it does look nice, but... (checks price) ... it's $1,000 per month!  PER.  MONTH.  Maybe that pricing makes sense for a $200 million company, but it's definitely too expensive for me.

There might be a few low cost commercial tools that could meet my needs, but I'm going to have to review them to see what they offer and how we might integrate them into our business.

My overall concern is that many people focus so much on the tool that they may not be critically evaluating the cost / benefit equation.  Maybe your business is all highly technical developers who can easily work with GitHub pipelines.  Maybe your company values beautiful, rich documentation that justifies the effort to develop fancy templates.  And maybe your company needs internal documentation for 500 users, in which case perhaps $1,000 per month is a bargain.

But again, given my experience with documentation, I'm not convinced that an elaborate documentation solution will provide more value than a simple one, given my current needs.

Update:  Lights, Camera, Action!

Erik Hougaard posted a great reply on Twitter.  He shared that he now primarily creates videos instead of written documentation.  This is a very interesting idea that I forgot about.  I have done a few product tutorial videos, but I don't usually think of video when a customer or user asks for documentation or instructions.  

I think it's a great idea, as recording a 1-3 minute video could potentially be much more convenient and effective than writing a 2-3 page step by step instructional document.  

Dmitry Katson shared that he's also switched to video tutorials instead of written documentation:

No more written documentation: Video only

This is truly fascinating.  When I wrote this blog post, I didn't even think of video.  So to learn that both Erik and Dmitry have essentially fully replaced their written documentation with videos was a big surprise to me.

Questions that come to mind about video content:

1. How do you produce consistent, high quality videos?  (with high quality audio)  Not every employee will be able to do this.  Or do you even need high quality?  Are impromptu recordings on a laptop with a headset sufficient for these short videos?

2. Is more than one person in your organization able to produce such videos?  i.e. can the process scale?

3. What video format (intro, outro, logos, overlays, graphics, etc.) do you use?  

4. How do you publish the videos?  If they are public videos for apps, presumably YouTube would work, but what about customer-specific videos for a PTE or process tutorial that cannot be posted publicly?  How do you host those videos, index them, and make them available to end users?  

Dmitry shared that he hosts the videos on Vimeo, while Erik noted that he will just record a Teams meeting and post it in SharePoint.

Truly fascinating!

A Journey

So I don't have any conclusions at this point, other than I'm sensing that it may not be easy to select a documentation solution that will replace MS Word.  

At the moment, I *think* I would like to have a solution that lets us publish docs to our web site.  This would avoid having to maintain and distribute PDFs, would facilitate updates to centralized docs, and it may allow us to gather metrics on usage of the docs pages.

But will such a solution work for our software products, Business Central customer per-tenant-extensions, and customer-specific user guides or documentation?  Or would we have to use different tools for different situations?

It will require some research to answer those questions. 

Steve Endow is a Microsoft MVP in Los Angeles.  He works with Dynamics 365 Business Central and related technologies.

You can also find him on Twitter and YouTube, or through these links:  links.steveendow.com