Software Documentation: 6 Best Practices That Work

Our modern world looks very different from it did prior to the industrial revolution. The access and evolution of knowledge has had a significant role to play in this transformation.

In today’s world, computer software is a key driver of the world economy. Unsurprisingly, global IT revenue is poised to surpass $4.8 trillion by the end of 2018, as this CompTIA report states.

However, the software industry is far from realizing its full potential. A study quoted by ZDNet stated that as of 2009, the average project failure rate was as high as 68%.

While this rate is improving, as a CIO.com article shows. The report by the Project Management Institute (PMI) study to show that the amount of money being wasted by inefficient project development saw a reduction in 2016 when compared to a earlier year. While this is good news, there a lot more to be done.

Why do software projects still fail? There are many reasons, for e.g., a lack of management commitment, cutting corners, inadequate project planning, flawed selection of technologies, scope creep, and insufficient communication. Read “Common Reasons why IT Projects Fail” to know more.

A big contributing factor lays in poor documentation. In many instances, a project manager will retain important aspects of the project plan in their head. As a result, these details are unclear to the rest of the team. Tasks and instructions must be spelled out verbally, with only half-baked information reached the IT architect. Communication remained words-of-mouth focused, resulting in an insufficient flow of information.

This example shows just how important software project documentation really is. It can make or break a project. If you want to ensure your project’s success, one of most important things is to ensure you have your project documentation in order.

In this article, to help you make sure that you get this aspect of project planning right, I will explain software documentation best practices.

Contents

More on the importance of software documentation
What are the various types of software documentation?
Software documentation best practices: #1 is automation
Best practice #2 for writing a software documentation: Create a document hierarchy
Software technical documentation best practice #3: Manage the documentation process
Best practice #4 for software development documentation: Visibly engage your team
Best practice #5 to write a software documentation: Use graphics and visual aids
Software development documentation best practices #6: Build and sustain knowledge

More on the importance of software documentation

Download Our Project Specification Template

We are all customers. Whenever something is of use to us, we are its’ customers. This basic premise is equally true in the IT industry. A project management software like Trello has its’ customers. A cloud computing platform like Amazon Web Services (AWS) has its’ customers. Unless customers understand the product, they can’t use it. The product will ultimately lose customers.

Extend this argument further. Are you an IT architect? Unless the business analyst spells out the business requirements of the customer of the proposed product, you can‘t design an IT architecture for the product/solution. The output of the business analyst is your input. You are the customer of that document!

Similarly, if the technical specifications aren‘t good enough, coders can‘t use them. On the other hand, if the test cases aren‘t well documented, the test specialist can‘t execute them. If a company monetizes their data using APIs, then the developers using those APIs are their customers. APIs need good documentation, otherwise, the ’customers‘ will find other APIs.

Are you an IT PM? When you present your project to the senior management for their review, or when the internal quality assurance team audits your project, your project documentation is the ’product‘. They are your customers. They need to understand your project from those documents.

To put it simply, expand your horizon when thinking about customers, and the importance of good software documentation becomes self-explanatory. Read more about this in “Need for better documentation”.

What are the various types of software documentation?

This question isn‘t a straight-forward one. The kind of project, i.e., services or product development influences the type of documentation needed. The project phase has a bearing on the type of documentation, for e.g., the execution phase requires a different kind of documentation than a ’Request for Proposal‘ (RFP) phase.

Broadly, the following are the broad categories of software documentation:

  • A proposal: A provider sends it to a prospective customer.
  • Before an organization approves a project, it undertakes due diligence. A feasibility study is a document that’s produced at this point.
  • Requirements analysis documents: Business analysts study customers‘ business requirements and translate it into technical requirements.
  • Software design documents: IT architects or analysts study the technical requirements and develop the design document. This will be an input to the development process.
  • Coding documents: This is a broad category. It includes the code, comments, and constraints if any.
  • Testing documents: Yet another broad category, this includes test plans, test cases, requirements traceability matrix with reference to test cases, test results, testing review logs, etc.
  • Review records: Either peer reviewers or independent quality assurance professionals may produce these. They review project artifacts and note their comments.
  • Guides and checklists: These can be or various kinds, for e.g., coding guidelines, review checklist, etc.
  • Project intellectual capital documents: Typically produced at the end of the project, these aim to enrich organizational process assets. In some cases, the organization might even want to file patent applications using these documents.
  • Project management documents: This is another broad category. Anything that comes under the ’Project Management System Summary‘ (PMSS) can be considered in this category.
  • Licenses: If a project procures software for the execution, the team needs to maintain licenses.

Read more about it in “Types of software documentation”.

Software documentation best practices: #1 is automation

This is a good solution for documents you create frequently. Remember that you will be able to use this approach for commonly-used documents only. This isn‘t the appropriate solution for documents for rare or special circumstances.

Let me illustrate with an example. When you submit a proposal to your customer, you can use an automated snapshot of company credentials. However, in the same proposal, you will need to manually create reference case studies since those pertain to certain industries or use cases.

Automating creation of common documents reduces manual errors. It saves valuable time. Consider using reputed 3rd party solutions for automating your documentation. One example is Templafy. HotDocs is another platform that enables you to automate documentation, furthermore, you can also create templates for frequently used documents.

Best practice #2 for writing a software documentation: Create a document hierarchy

You might be asking “How to write a software documentation that‘s effective?”. The key operative word here is “effective”. You need to define effectiveness first. This varies according to the context.

If you are going in for a meeting with your customer trying to explain the features of your ’Platform as a Service‘ (PaaS) offering, an effective document is what helps you to sell. Think about it for a moment. A start-up trying to launch their web app is looking for a PaaS provider to expedite their development. Will they buy from you by just seeing an elaborate document? They probably won‘t!

Read How We Helped a Marketing Company to Build a Back-Office Custom Ads Dashboard

In this case, the customer would need a demonstration of how quickly a web app can be created using your PaaS. A document will be required in this discussion, but only for anchoring the discussion. Your presentation to this customer needs to focus on the demonstrable features of your PaaS, while the document just helps to remind customers about the value of your platform. Such a document should be prepared with utmost care. It should do nothing to take away the focus from the demo, however, it should convey what you offer.

Compare this with a document that your development team will use as a checklist during their development process. This document should contain plenty of details. Differentiating documents in this manner is called ’creating a document hierarchy‘. You categorize your documents into internal, external, and customer-facing. Read more about this hierarchy here.

Pay utmost attention to the customer-facing, and external documents. Put your best people on the job for these. On the other hand, try techniques such as automation for internal documents, to improve efficiency.

Software technical documentation best practice #3: Manage the documentation process

To get sustained value from your IT documentation, you need to manage the processes that produce them. If you only react to an instance of sub-optimal documentation after it has reached your customers, you aren‘t doing enough. Proactive management of the process is imperative.

Build a system for creating the software technical documentation. Establish a team structure, with specific roles and responsibilities. Formulate guidelines for creating documents. Build a process to test the documents. Establish metrics for various stages of the documentation process.

Can your team use the review checklist you recently rolled out? How many defects could they detect using it? If you unveiled a guideline to create RESTful APIs recently, are your developers able to do their job using it? How many questions did your call-center receive from users of your SaaS product? How often are your call-center representatives solving ’Level-1‘ tickets using the knowledge database they have?

The above are just a few examples of metrics you should establish. The point is that you can only manage what you measure. Read “The importance of implementing effective metrics” for more details.

Develop a clear standard of performance in your IT documentation team. Reward practitioners that produce quality products. Coach and manage the performance of practitioners that consistently produce sub-optimal documents. Make sure they can get first-hand feedbacks from users of their documents.

Best practice #4 for software development documentation: Visibly engage your team

This point is a continuation of what I just stated about managing the process. Let’s understand a hard reality. A software isn’t a tangible good like that fancy watch or smartphone. It’s intangible, the value of a software is experienced by using it first. Consequently, every step of the software development process has abstract elements. Software documentation aims to capture these abstractions into words and/or graphics. That’s not easy!

While you certainly need to build a team that has the right talent for software documentation, you also need to provide them with the best tools. This can include automation platforms, templates, and aids. The team should clearly know where they can find help. Your team should also be motivated by the intrinsic value of their work. That’s the only way for sustained motivation in a team.

Your team should be able to see how their customers are deriving value from what they produce. This should be as clearly visible as possible. Hearing directly from your customers, seeing how your customers use their work products make a big difference. Read more about employee engagement in “8 results-driven reasons you need employee engagement”.

Best practice #5 to write a software documentation: Use graphics and visual aids

When documenting in the software industry, always keep in mind that a software is just a tool. If you are selling your software to a start-up, they are likely buying it to support their core business. Their core business has a higher priority for them, not your software! Consequently, they will look to spend as less time possible on your software, while they try to spend as much time as possible on their core business.

It follows that they will look to spend even less time on your documentation. You need to make your documents as easy for them as you can. Using graphics and other visual aids is hence an important one among IT documentation best practices.

I illustrate this with a few examples, as follows:

  1. If you are writing a user manual, consider using screen prints and schematic diagrams.
  2. If your IT architect is writing up the architecture decision matrix for a review meeting with your customers, then he should use clearly enumerated blocks to represent components.
  3. If you are presenting to your customer as part of an RFP evaluation process, create a clear flow diagram depicting how your IT solution will work.
  4. If you are submitting an RFP for annuity IT application maintenance contract and need to show progressive cost savings to your customer, make sure you use relevant graphs and charts.

Read more about this best practice in “IT documentation best practices”.

Software development documentation best practices #6: Build and sustain knowledge

You and your team will likely learn a lot from your software documentation endeavor. No amount of theoretical knowledge can replace practical hands-on learning. This will be the case for your team too.

Establish a robust process to capture the lessons learned on the job. Build a knowledge base, however, don‘t stop there. You need to encourage your team to use it. The team should also enrich this knowledge base in an ongoing manner.

Entrust responsibility of maintaining the knowledge base to specific persons. Reward usage and enrichment of the knowledge base. Building a ’Process Asset Library‘ (PAL) is a valuable experience. Read more about PALs in “What is process asset library (PAL) in context of CMMI?”.

Download Our Project Specification Template

Aran Davies

Blockchain Expert | Developer | Writer | Photographer
Aran Davies

Latest posts by Aran Davies (see all)