Tips In Writing A Good Documentation for a Package

Jed Tony
Jed Tony
Jul 10 · 3 min read

A software package documentation is a document that contains information about a package that is to be used with a programming language, or as a plugin for a framework. This documentation plays an important role in determining whether a package will be used by others or not. Often times, most packages with lots of awesome features are not used because of poor documentation. In fact, this article was written as a result of the pains I have suffered from trying to understand poorly written documentation.

This article will be considering some features that have been found useful in various documentation. I will be using as a case study Maatwebsite/Excel package ( This is a package that makes it easy to work with spreadsheets in Laravel, a PHP framework). You can check out the website by clicking this link.

You should set up a website/webpage for your package. This should be different from your README.md in your Github repo. You can host a free webpage on Github pages or on readthedocs.org. The suggestions given in this article should be implemented on the website/webpage that you set up.

Note that this article is not meant to give you a format for writing documentation, but it outlines features that users have found useful when being included in the documentation of a package.

Some Features of a Good Article

🚀 Laravel Excel is intended at being Laravel-flavoured PhpSpreadsheet: a simple, but elegant wrapper around PhpSpreadsheet with the goal of simplifying exports and imports.

2. Requirements: This should include the setup required for your package, also the fundamental knowledge required e.g

PHP: ^7.0
Laravel: ^5.5
PhpSpreadsheet: ^1.6
PHP extension php_zip enabled
PHP extension php_xml enabled
PHP extension php_gd2 enabled

3. A quick start guide: This should be a series of steps that when followed will help a user be able to implement a working example of the basic feature of the package. The duration of implementing this should not be more than 10–15 minutes, though it can be longer depending on the nature of the package. If it is a frontend package or a code to be implemented on the frontend of a website, a link to a live demo on codepen or codesandbox should be included.

4. Outline the unique features of your package. E.g 2FA, improved dependency management or whatever as the features pertain to your package. In the case of Maatwebsite/Excel, it is limited to
Exports and Imports.

5. Under each feature mention the functionalities for that feature and explain them with code samples. Your code samples at this point should be built on the quick start guide written earlier.

6. Problems and bugs: Often times we encounter bugs if there are bugs that you encountered while making a fresh installation of your package include it in your documentation. Also, write on how to solve it, do not assume that your user should easily find a solution, no matter how small the bug is. An example can be found below:

If you encounter an error like “class Excel not found”, simply include this in your controller use Maatwebsite\Excel\Facades\Excel; .

These are just a few things that I have found helpful in reading certain documentation.
Feel free to add what you have found helpful in the comments below. I would be glad to rewrite this article to contain specific features that other people would like to see in documentation.