Tips on Designing a Good Framework, Library, or Plugin — Part 1 — Documentation

Posted in engineering

I have created numerous framework, mostly for internal use. From the experience, I learned on how to design a good framework, library, plugins, or anything that might be used by other developers.

Note that everything written is from my personal experience, knowledge, and opinion. This is a personal tips, and it might be against your best practice, so please read it with open mind and focus on the positive.

The term framework later will be used as a generalization of framework, library, or plugins.

Documentation

Every framework require a good documentation for people to be able to use it without any issues. You might be on the side of self documenting code, or the side of extensively commenting everything you can, the goal here is to do both sides averagely.

Good documentation is result oriented, which means you guide people on how to use your framework to achieve the result that they wanted. Bad documentation is a long narrative that contains too many information you make the reader confused on what to do.

If there are external information, using a link to the external information is better than explaining the external information on your documentation.

Axios is a promise based HTTP client for the browser and node.js.

As you can see above, promise is a new feature on JavaScript, and some people might need to know about this new feature, thus it is a good external information to give to our reader, and we used link to provide that information.

Axios is a promise based HTTP client for the browser and node.js. Promise is a new feature on javascript that makes HTTP request easier to handle and consistent.

Above is a bad example on how to write documentation, the main focus of our documentation is our framework, and we are not writing a tutorial, so we don’t have to explain everything that we wrote on our documentation. Explaining external information as above is a sign of bad documentation.

Always Put Code First

As a developer, we sometimes have tight deadlines, and we wanted to scan the documentation as fast as possible and get our job done. It means we are looking for a code or instructions that we can run to get our result.

Axios installation documentation.

Again, using Axios as an example. We were given a code on how to install Axios right away, and right below the installation instructions, we were given a code on how to use Axios.

Axios usage example.

This makes it very easy for us, developers, to scan the documentation fast and start writing our code, based on what the documentation instructs.

To make it even better and to reach more audience, we can link NPM, Bower, and CDN above to an external information to help reader learn more about it if they wanted to know or doesn’t have any idea about what is NPM, Bower, or CDN is ( this should be common knowledge for web developers though, so it might not be necessary, again, think about who is your audience, and do you need to explain the external information or not).

Using Axios is easy, you just install it from NPM and you’re good to go. Just run npm install axios on your command line. If you don’ want to use NPM, you can use Bower and run bower install axios, if both of them is not what you want, just use CDN that you can use at <script src=”https://unpkg.com/axios/dist/axios.min.js"></script>.

Above is an example on bad documentation, because it is narrative, and being narrative means it will be a long text and a lot of information that is distracting the reader.

Document Your Public API

Functions, classes, properties, enums, types, etc. All of this is something that you should document. Failing to do this would make the framework harder to learn and use.

You can document it on the documentation, or do it right away on the code. Some smart editor like PHPStorm or Visual Studio Code, benefits from code documentation and can provides the code documentation right when our user try to use our API.

Example of code documentation is as below

/**  
*  
* Expose the web application so it can be accessed.  
*  
* @param int $port Port on where to bind our web application. Port must be within the range of 5100 - 5110.  
* @return boolean True if successfully bound, false otherwise.  
*/  
function exposeApplication($port)

Note that the format of code documentation is different on each programming languages, and some smart editor might have its own format on how to format the code documentation too.

Explain Special Case

In the example above, there is a special case. The port number can only be 5100–5110. Documenting a special case like this is really important, and making it easy for the reader to discover why they are having issue when they set the port to 5000. Explaining the reason on why you do this is also nice to be included.

The port 5100–5110 is scanned by the framework internal load balancer, that is why you have to set the port to 5100–5110. Using other port would make the load balancer to fails and the app won’t run because the load balancers fails to detect our app.

Example on explaining special case as above really helps and provides the reason on why there is a special case like this.

Follow the Standards

While there might be no de facto standard on writing documentation. There are few common sense on writing documentation.

Google wrote guidelines on writing documentation, I personally take some of the tips from the guidelines, and ignore others that I don’t see fit.

If there are some kind of guidelines or standard defined on your community, like when you are writing documentation on React, they expect you to write documentation code example using JSX, because people find it easier to read, then you must try to follow the guidelines so it is easier for others in the same community as you to read your documentation.

Conclusion

Writing good documentation is not hard, nor it is easy. It is a subjective matter on how each people see documentation. Technical people like me found it easier when the documentation is written with the tips above. If you are an artist, musician, designer, architect, etc. The style of documentation that fits your style might be different.