Skip to main content

Documentation

Documentation is any communicable material that is used to describe, explain or instruct regarding some attributes of an object, system or procedure, such as its parts, assembly, installation, maintenance and use.

Documentation is a part of any Open Source project including things that are not software. Good documentation practices are important for the success of the project as it helps users and contributor effectively uses the program but it requires that the writer considers the perspective, knowledge and experience of the reader. Considering their perspective is key to ensuring a sustainable project.

Types​

There are several types of documentation that are commonly used in open source projects, including:

  • User documentation: This type of documentation is geared towards end users of the software, and explains how to use the different features and functions of the project.
  • Developer documentation: This type of documentation is intended for developers who are contributing to the project, and explains how to build and modify the source code.
  • API documentation: This type of documentation provides information about the application programming interface (API) for the project, including a list of available functions, methods, and classes, and how to use them.
  • Release notes: This type of documentation provides information about the changes and new features in each release of the project.
  • FAQs: This type of documentation provides answers to common questions and problems that users may have when using the project.
  • Tutorials: This type of documentation provides step-by-step instructions for completing specific tasks with the project.

User Documentation​

This document is mostly delivered for end-user who actually want use the product themselves, to understand and complete a certain task.

  • How-to guides – Guides the user to complete a task or a predetermined goal.
  • Tutorials – Learns a concept by following a series of steps concept
  • Technical Reference – Describes the technical detail of the product (Software requirement specification, software design documents and so on)
  • Administration Guide – Enables the administrator to refer to this after installing an application
  • Configuration Guide – Allows the administrator to refer to this document for configuration parameters.

Developer Documentation​

This documentation refers to system related documentation.

  • API documentation –Specifies how to invoke API calls and classes, or how to include API in the code that is being developed. Release Notes – Describes about the latest software, feature releases, and what bugs have been fixed. Usually this document is a text file with a filename extension (.txt).
  • README – A form of documentation, it is usually a simple plain text file called Read Me, READ.ME, README.TXT with A high-level overview of the software, usually alongside the source code.
  • System Documentation – Describes the system requirements, includes design documents and UML diagrams.
  • License – Describes the license and terms the software

Just-in-time Documentation​

Situation may arise, where a just-in-time document quickly serves the support for customer-facing documentation. The user need not have to refer to any documents or FAQs for information.

Documentation Tools​

It is recommended that documentation tools be common across your development team, so that it can be easily accessible within the environment, and you need to initiate that the documentation becomes a mandatory part of the Software development life cycle process. For example, GitHub is a cloud-based do my papers application, which serves the purpose for code developers and authors.

Writing Good Documentation​

To write good open source documentation, there are a few key things you should keep in mind:

  • Be clear and concise: Documentation should be easy to understand and should not contain unnecessary information. Use simple language and avoid technical jargon whenever possible.
  • Be thorough: Make sure that your documentation covers all of the important aspects of the project, including its features, functions, and usage.
  • Use examples: Wherever possible, use examples to illustrate key concepts and show how to use different features of the project. This can make the documentation more accessible and easier to understand.
  • Keep it up to date: As the project evolves, make sure to update the documentation to reflect any changes or new features. This will ensure that the documentation stays relevant and accurate.
  • Get feedback: Ask other contributors or users to review the documentation and provide feedback. This can help identify any gaps or areas that need clarification.

References​