Software Documentation Types and Best Practices

Software Documentation Types and Best Practices

Agile and waterfall approaches

Types of documentation

  • Product documentation
  • Process documentation
  • System documentation and
  • User documentation

Product: System documentation

Requirements document

  1. Roles and responsibilities. Start your document with the information about project participants including a product owner, team members, and stakeholders. These details will clarify responsibilities and communicate the target release goals for each of the team members.
  2. Team goals and a business objective. Define the most important goals in a short point form.
  3. Background and strategic fit. Provide a brief explanation about the strategic aim of your actions. Why are you building the product? How do your actions affect the product development and align with company’s goals?
  4. Assumptions. Create a list of technical or business assumptions that the team might have.
  5. User Stories. List or link user stories that are required for the project. A user story is a document written from the point of view of a person using your software product. The user story is a short description of customer actions and results they want to achieve.
  6. User interaction and design. Link the design explorations and wireframes to the page.
  7. Questions. As the team solves the problems along the project progression, they inevitably have many questions arising. A good practice is to record all these questions and track them.
  8. Not doing. List the things which you aren’t doing now but plan on doing soon. Such a list will help you organize your teamwork and prioritize features.
  • Use links and anchors. They will help you make the document easier to read and search as readers will be able to comprehend the information gradually. For instance, you can provide links to customer interviews and anchors to previous discussions or other external information related to the project.
  • Use diagramming tools to better communicate the problems to your team. People are more likely to perceive information by looking at the images than reading an extensive document. Different visual models will help you to perform this task and outline requirements more effectively. You can incorporate diagrams into your requirements process using the following software diagramming tools: Visio, Gliffy, Balsamiq, Axure or SmartArt in Microsoft Office.

Software architecture document

Source code document

  • HTML generation framework and other frameworks applied
  • Type of data binding
  • Design pattern with examples (e.g. model-view-controller)
  • Security measures
  • Other patterns and principles

Quality assurance documentation

  • Test strategy
  • Test plan
  • Test case specifications
  • Test checklists
  • The list of features to be tested
  • Testing methods
  • Timeframes
  • Roles and responsibilities (e.g. unit tests may be performed either by the QA team or by engineers)

Maintenance and help guide

Product: User documentation

  • end-users
  • system administrators
  • FAQs
  • Video tutorials
  • Embedded assistance
  • Support Portals
  • Functional description — describes the functionalities of the product. Most parts of this document are produced after consultation with a user or an owner.
  • System admin guide — explains different types of behaviors of the system in different environments and with other systems. It also should provide instructions how to deal with malfunction situations.

Process Documentation

General practices for all types of documents

Write just enough documentation

Documentation is an ongoing process

Documentation is the collaborative effort of all team members

Hire a tech writer

Final word