MINIMUM VIABLE SOFTWARE DOCUMENTATION PLANNING


Version Date Author Reason
0.1 16 Mar 2021 Derek First draft
Work in progress! currently in draft.

Audience

Business owners, project managers, software developers and technical writers.

Purpose

Most projects have limited funding and resources.

This document will help you plan and prioritise the software documentation management task by:

  • providing a framework for discussing and negotiating documentation priorities and tasks with your team
  • specifying user groups and user tasks
  • specifying document types suitable for user groups and user tasks
  • identifying higher priority "must have" documents over "nice to have" documents
  • estimating the software documentation maintenance costs across a development cycle
  • producing a lean documentation MVP with zero waste that meets the needs of different user groups

This document synthesises information from the following sources:

Example

You are a newly hired Technical Writer. Your manager is paying you $60,000 per year to produce technical documents for a software project. You need to present a Minimum Viable Documentation MVD plan within two weeks and discuss your reasoning for your proposed priorities with the team.

Foundation concepts from Google

  • Prefer the good over the perfect
  • Minimum viable documentation
  • Update docs with code

Foundation concepts from Microsoft

  • Who is your audience? What do they want to accomplish?
  • What kind of content best meets the customer's needs and business goals?
  • How will you measure success?

Understanding the Procida model of software documentation 'types'

This section is a quick summary of the main points in Procida's system and assumes the reader is familiar with his system. If you are not familiar with his work, please read about the documentation system first.

Procida says software documentation should be "explicitly structured around four different functions"3, each with a different purpose and audience skill level.

The four functions are:

  • Tutorials - learning lessons for Total Newbies
  • How-to guides - steps towards a goal helping users who are familiar with the software
  • Technical Reference - encyclopedia of software functions, methods, API, etc. for power users
  • Explantion/ Discussions - broader contextual explanations

Procida says unstructured software documentation (e.g. an unstructured wiki or collection of help documents) will implicitly contain the four functions but will inevitably be "pulled in different directions at once"1 and fail to meet the needs of specific user groups.

Characteristics of Tutorials

Procida says that producing and maintaining tutorials may comprise up to 75% of the total documentation effort and "need regular and detailed testing".

Todo

Need to check that tutorials use 75% of resources. I assume this is for projects with very frequent and significant development cycles.

Characteristics of tutorials:

  • simple and robust enough to work on any and every system, "cast-iron reliability" - no exceptions
  • learning by doing - immediate feedback/ signs of learner success
  • "hand held baby steps"
  • simple tools and operations
  • simplest way to do something - not the most efficient
  • title of tutorial tells the learner what they will do - not what they will learn
  • the technical writer decides what the user will learn
  • friendly and supportive tone

Characteristics of How-to guides

Procida describes how-to guides as recipes.

Characteristics of how-to guides:

  • solves a specific user problem
  • the title of the guide starts with the phrase "How to"
  • the user is assumed to understand the basics (the tutorials)
  • the user decides what they will learn
  • can be clustered under broad user-focussed task headings (information architecture)
  • friendly and supportive tone

Characteristics of Technical references

Procida says that many developers automatically think that technical references are the sum-total of software documentation.

Characteristics of technical references:

  • the 'base' is automatically generated from code
  • automatic reference should be augmented with technical writing
  • augmentation might include best practice, examples of use and how to avoid potential problems
  • has a consistent document structure like an encyclopedia
  • does not include "explanation, discussion, instruction, speculation, opinion"
  • dry and austere tone

Characteristics of Explanations/ discussions

  • provides context
  • may include differing opinions
  • "exaplain why things are so - design decisions, historical reasons, technical constraints"
  • relaxed tone

I think contextual explanations are "nice to have" if you have limited resources.

Procida's graphical model

Procida presented this graphic. He describes how the four functions often overlap.

I think this graphic is visually complicated and hard to understand.

Example

You have decided to use three of Procida's four document type/ functions for your MVD: Tutorials, How-to guides and Technical references. Your target audience will be: Total newbies, Intermediate users and Power users.

Software documentation management concepts from Cameron Shorter's website

This section describes several ideas that are relevant to software document management from Cameron Shorter's website.

Understanding the Shorter model of software documentation 'types'

Shorter has written extensively about his document type taxonomy here (from 2018).

Shorter's list of document types. I have highlighted the document types that match Procida's three functions.

  • Solutions
  • Demos
  • Case Study
  • White Paper
  • Features
  • Site Map
  • Conceptual Overviews
  • Quick Starts
  • Reference Docs
  • Tutorials
  • Training Course
  • Developer Guide
  • Knowledge Base
  • Glossary
  • Tooltips
  • FAQ Troubleshooting - Error Codes
  • Release Logs
  • Community Forums

In this article Shorter took Procida's system and displayed it with his own perspective.4

Characteristics of Shorter's document types:

  • includes community forums as a component of the software documentation task
  • identifies the audience size as a continuous variable - from generic to specific
  • identifies documentation as a continuous variable - from polished to evolving
  • identifies the concept of a 'polished core'

Shorter also includes other documents which I think are "nice to have" if you have limited resources.

  • elevator pitch
  • overview
  • quickstart

Community forums

A community forum could be implemented as a simple StackOverflow tag or Reddit subreddit. Team members with expertise will need to respond to user queries quickly. This time should be accounted for as part of the overall documentation task.

Alignment with Microsoft's content ideas/ document types

The 'Content ideas for specific user needs' section of Microsoft's Content planning page lists several possible document types. I have chosen the three content ideas that align with the three document types discussed above.

  • Complete a simple task or use a simple feature in an app
  • Complete a complex task or use a complex feature in an app
  • Get answers and expertise from a community/ Troubleshoot a problem

Example

You have decided that your MVD polished core will include Tutorials, How-to guides, Technical references and Community forums. The community forum will serve as a 'large net' and will leverage expert users willing to volunteer their expertise to less experienced users.

Additional software documentation management ideas from Shorter

Shorter discussed several relevant management ideas for the MVD technical writer:

  • write what you can maintain/ a maintenance strategy
  • documentation releases will be synchronised with the code release cycle
  • glossaries/ controlled vocabularies
  • document templates and style guide

Glossary

The purpose of the Glossary is to 'control the vocabulary used within the project and ensure that all user documentation 'always uses the same language'. Shorten describes glossaries here

Document templates

Shorten describes document types in detail here. You should also look at Porcida's document characteristics at the top of this document.

Style guide

Google and Microsoft have several of resources to help technical writers develop style guides:

Example

You have decided to align the document release cycle with the code release cycle. You have added a style guide, document templates and a glossary into the polished core. You have budgeted a portion of your time to document maintenance and answering questions on the community forum.

Developing a list of user learning tasks and topics

You will need to work with the team to make a list of tasks that users want to perform or problems users want to solve. There should be two lists:

  • Tutorials topics - a list for tasks/ topics for Total Newbie users.
  • How-to guides - a list for intermediate users. Start the titles of these documents with "How to ...".

Workplan for a Minimum Viable Documentation for a software development team

  1. Explain and discuss what you plan to do with the team
  2. Identify existing documentation "meta resources", if any.
    • Software release calendar
    • Style guides
    • document templates
    • documentation budget - initial and ongoing
  3. Identify Glossary, if any
  4. Get buy in on document type classification.
    • Tutorials for Total Newbies
    • How-to guides for New-Intermediate users
    • Technical reference for Power users
  5. Identify existing documentation resources
    • File location
    • Date updated
    • Document type
    • Version of software referenced
    • Pageviews/ usage stats
  6. Generate a report of documents currently available
  7. Work with the team to generate two lists of topics and tasks for the Tutorials and the How-to guides
  8. Work with the development team to understand how technical reference documentation can be efficiently generated from code
  9. Identify gaps in the polished core
  10. Identify maintenance timeline and budget for each document
  11. Identify a publishing pipeline - outline / write / review / publish
  12. Start writing
  13. Incorporate user feedback

MVD deliverables

  • Target audience: Total Newbiews, Intermediate users, Power users
  • Document types: Tutorials, How-to guides, Technical reference, Community forum
  • Meta documentation: Software release plan, Documentation budget, Glossary, Style guide, document templates
  • Audit of existing documentation
  • Prioritised task list based on the audit report

Todo

  • standard referencing style
  • section on toolchains
  • incorporate Etter

SOURCES


  1. Procida, D, 2020, The documentation system, Divio, https://documentation.divio.com/
  2. Shorter, C, 2019, Why is the QGIS docs team struggling?, http://cameronshorter.blogspot.com/2019/12/why-qgis-docs-team-is-struggling.html
  3. Procida, D, 2020, TWhat nobody tells you about documentation, Youtube/ PyCon AU, https://www.youtube.com/watch?v=t4vKPhjcMZg&ab_channel=PyConAU
  4. Shorter, C, 2019, Inspiring techies to become great writers, http://cameronshorter.blogspot.com/2019/02/inspiring-techies-to-become-great.html
  5. Shorter, C, 2018, Technical Documentation Writing Principles, http://cameronshorter.blogspot.com/2018/06/technical-documentation-writing.html
  6. The Good Docs Project, Captured 2021, Information Architecture, https://thegooddocsproject.dev/ia-guide/ia-static.html
  7. Google developer documentation style guide https://developers.google.com/style/word-list