Documenting your software product
Documentation stakeholders, and what should be in, or not in, the public domain
Information silos and supporting rapid growth
When launching your new software product, it’s important to ensure it is thoroughly documented, not least for the specialists and end users for whom it will be their ‘daily driver’.
There are several other important stakeholder groups that stand to benefit, not least, the Sales and Marketing teams who need to address questions from prospective customers during initial enquiries and later during more intensive due diligence assessments. If you can quickly find or ‘point to’ the answers to critical questions it immediately engenders confidence in the supplier.
Having a considered product documentation strategy is important for startups and organisations going through a rapid phase of growth. It’s important to avoid information silos, to consolidate what you know and to reduce the need for having to bring overworked engineers ‘out of the zone’, to answer the same questions, again and again.
We don’t want to see knowledge buried in slide decks that are sent point-to-point, and not shared internally with the wider team.
Having a full documentation stack allows technically literate non-engineers address to complex topics on their own.
Documentation is necessary to train your own staff as well as your customers. It is an essential part of the support tool-chain. If somebody raises a question, and the answer is not in your knowledgebase, the support analyst or a dedicated expert should immediately pen an answer to the issue and add to FAQs, or troubleshooting tips. The response to the question should contain a link to the newly penned article. You can bet your life that if one person has that question, others will too - why ‘waste’ the answer by burying it in a support ticket where others might not see it, when a new article will add to the ‘commons’ and benefit others?
Keep it in control, but don’t overburden it with length reviews signed in triplicate
Regulated environments
If you are a software development organisation providing applications that will be used in a regulated environment, it’s easy to fall into the trap of thinking you are the regulated company. You are not.
System and support documentation needs to be accurate and dependable of course, but it is often a fact of life that it gets de-priotised in favour of getting the latest release out of the door. It’s all hands on deck finalising and testing the code and producing the essential SDLC documents needed for the release. We make excuses that we will rustle up some documentation after the software has shipped and we have had a little breather.
Acknowledging this, we need to take an agile, continuous delivery approach.
We create a small team with one ‘managing ‘editor’ responsible for content, style and quality. They will enrol a number of additional editors and many more ‘contributors’. Each of these editors and contributors are likely to have other principal responsibilities - business analyst, engineer, support analyst, project manager etc., but that does not stop them from being included in the Documentation Team and tasked to write, review and update articles within their areas of expertise.
Internal project management tools (Jira, etc.) can be used to task SMEs to write, review or update an article. If you are using something like Confluence as your document library, those Jira tickets can be linked to the associated article to provide traceability if required. Reviews can be done ‘off document’ and written up in the ticket until the article is ready for publication.
In some cases, particularly with support issues, an expert will write an article and publish it quickly, without review. In some cases 80% good, is good enough, and it is probably enough to move the user through a blocking issue.
This is why we have smart people on the team, they know the answers, and just as importantly know when they don’t know the answers. So they ask someone for help.
An 80% article can be iterated and polished to 95% the next go around.
Photo by Gabriel Sollmann on Unsplash
Public domain
I am huge fan of putting most of the information about a software product in the public domain.
Without a login required.
It’s not as though you are sharing the source code right? [Be quiet Open Source Software people! - Steffan].
Your competitor is not going to be able to read your documentation, reproduce your software, test it to GAMP, FDA, EMA etc. standards and then steal all your customers [Be quiet AI people! - Steffan].
Even if they do, you will have moved on, established your reputation, generated brand recognition and focused on delivering the best possible customer experience.
As Nike would say, ‘Just do it!’.
