Documenting a software project is one of the most easily ignored part of development. If you are looking to start documenting a new or complete project you could use the tools and process described below for descriptive documents.

Types Of Documentation

A software project usually goes through different stages needing different types of documents.

At each stage certain type of documentation is to done to help better understanding from teams and freeze the thoughts which are to be followed for development.

Some of the document types are listed here:

  • Requirement : BRD, User Stories, Component Diagram, Feature List
  • Design : Mock Screens, ER Diagrams, API, JSON, Error Codes
  • Implementation : Code Comments
  • Testing : Test Cases
  • Evolution : Backlog

Best Tools For Documenting

Sphinx

Sphinx makes it simple to create beautiful documentation which can be created and maintained by developers. Being a widely used tool you can find different examples here.

It is highly customizable and offers a simple way to export docs in html or pdf should you need to.

Jupyter Notebook Documentation using Sphinx

Swagger

If you think of creating any documentation for api's yaml based swagger will offer you everything you need.

Swagger Editor provides a neat view to create yaml or json based api docs. Swagger UI can be used to display docs to team.

It might not be a great idea to present a length word doc for API List to a developer. Although something like a swagger can be more receptive and easy to work with.

Redoc

Instead of using swagger ui you can also present your yaml docs into amazing html docs using redoc. Its really simple to integrate and looks elegate.

Draw.io

A versatile online tool to create technical documents. You can create all sorts of workflows, diagrams, flowcharts and much more.

You can easily save your work offline and export into jpeg or pdf format for sharing with your team.

Benefits Of Using This Tools

  • Swagger allows for standard interface document across all teams. This increases clarity and decreases change requests.
  • Sphinx ensures flexibility to document any type of project. Project structure and style can be varied per project basis.
  • After initial setup for the above tools, additions and modifications can be made very fast.
  • Swagger, ReDoc and Sphinx can be easily integrated in the CI and CD pipeline to save deployment time for this documents.

Conclusion

Documenting a software project not only allows new members on the team to understand the project faster but also enable effective cross team collaboration.

This simple tools can help you save time spent documenting and ensure sufficient details for new and cross team members to understand faster.