未加星标

Writing Good Documentation for Your Open-Source Library

字体大小 | |
[前端(javascript) 所属分类 前端(javascript) | 发布者 店小二05 | 时间 2018 | 作者 红领巾 ] 0人收藏点击收藏

Just a few years ago, developers often underestimated the art of writing docs and the value of having good documentation. If you look into the stone age (read: ten years ago), you will find that many libraries, perhaps aside from the most used ones, lacked good, or even any, documentation. Developers often expected that a few code examples would be enough for a newcomer to grasp what they’d had in mind and how to use their work.

The growth of open-source, though, demanded that documentation be written more and more with the end-user in mind . Corporations realized that presence in the open-source world is a valuable asset for attracting new clients and new developers. Open-source projects build credibility and establish reputation. Thus, the incentive to write solid docs became more and more important.

Another reason that I’d attribute primarily to the growth of Node as a popular technology, is competing libraries within ecosystems ― a situation rarely seen before the advent of npm. In python, for instance, there usually is one way to do one thing. In javascript, before Node, there also weren’t many libraries to do one thing in different ways ― just think about any popular alternatives to jQuery.

Nowadays, though, we can pick and choose our technology stack, and developers of these libraries and frameworks put in extensive effort to make learning and using them as painless and quick as possible . JavaScript developers can choose between Angular, React, Vue and many other, less popular frameworks on the front end and Express, Koa or Sails on the back-end, in addition to a million other libraries in between.

Components of a good documentation

There are many parts to a documentation, among others:

Readme Reference Guide Cookbook Blog post

Each of these fulfills different purposes, and the boundary between kinds of docs is sometimes blurred.

Readme

The readme file is often times the first contact potential users make with your product. It can be thought of as a bit of a combination of each other type of docs, but is in some ways unlike any of them. Readme is how you sell your open-source library. Note, though, that you should be brief and informative.

Begin by describing what your library helps your users with and what problems of theirs it solves . You can try giving examples of common use cases. A well-written opening paragraph is a great start to any readme. If your readme is longer than one and a half pages, a good practice is to include a table of contents.
Writing Good Documentation for Your Open-Source Library

Image source

List prerequisites and dependencies that the user should have and describe the installation process. Show a basic example of code, even better if it’s a real use case, and link to a more detailed documentation.

Finally, include a license and list contributors. You can also include a paragraph on how to contribute to your library. Remember, open-source is based on respect for each other’s time, and if your potential contributors can get up to speed on how to get your library running, everyone is a winner.

Reference

A reference is perhaps the most technical document of your documentation. Its purpose is to list all functions your library exposes; their expected inputs, outputs and side effects; purpose and implementation examples. Examples in the reference should be as isolated and self-contained as possible.

A reference is often times generated automatically, and there are multiple solutions to simplify working with it and updating it, however, you should remember that a reference that is exclusively computer-generated may be difficult to understand for your users. You should make an effort to include at least a sentence of your own written explanation per item in the reference.

Also, certain developers may find it helpful to understand specifically how a particular function is implemented. A nice-to-have feature, although certainly not a must, is a direct link to the function implementation in your library’s code.

Guide

A guide is, in essence, a tutorial helping your user navigate through all the features of your library. In the case of large, general-purpose, opinionated frameworks, the guide may be the largest document of the documentation.

Begin your guide by outlining its scope and establishing what prior knowledge the user is expected to have. For example, if you’re writing a library that helps with managing HTTP requests, the user would be expected to at least be slightly familiar with the basic concepts of the subject.


Writing Good Documentation for Your Open-Source Library
Image source

Start at the beginning cover the most basic topics first, and gradually move towards more complicated ones. A good starting point is always the installation processes for different systems. It may be useful to imagine a group of people sitting in front of you who you want to explain your product to. Remember that in this case, it is more respectful to your users to over-explain than leave important concepts unclear.

Include pictures and diagrams where relevant, as well as code examples. You may want to make the code in your documentation as complete as possible to allow the user to simply copy-paste certain parts, but it should be logically split and interspersed with comments and remarks on general applications of features exemplified in the code.

Remember to also test your guide. If the user copy-pastes every code example in the guide, it has to work. I can’t stress enough how frustrating it is for the user to have code examples from the docs not work.

Cookbook

In the case of large, general-purpose libraries, the cookbook is a collection of in-depth solutions for common problems your users may face while using your library. Unlike the guide, which builds on earlier concepts, each recipe in the cookbook should be self-contained. Also, applications of features necessary to solve a problem can and should be explained in more detail than in the guide.

Cookbooks aren’t necessary in cases of small and focused libraries, and should be considered only when discussing concepts that require greater complexity than you could reasonably put into the guide. As such, the cookbook can be considered a collection of short tutorials on how to accomplish a desired result.

Additionally, while the guide should focus primarily on your own library, in the cookbook recipes linking to other docs and showing integration with other libraries are encouraged. Further, you can explain why you use some language features over others. That helps your user not only become more proficient at using your library, but also the programming language in general.

Finally, you can include examples of when not to use certain solutions or show off incorrect code examples or anti-patterns. However, remember to visibly distinguish them from the correct examples.

Blog post

A blog post, while perhaps not strictly a part of the documentation, is still an important piece of information that your users can appreciate. While the other parts of the documentation focus on how to apply your library to relevant use cases, your blog post should explain why that was needed in the first place.


Writing Good Documentation for Your Open-Source Library

本文前端(javascript)相关术语:javascript是什么意思 javascript下载 javascript权威指南 javascript基础教程 javascript 正则表达式 javascript设计模式 javascript高级程序设计 精通javascript javascript教程

tags: your,library,documentation,should
分页:12
转载请注明
本文标题:Writing Good Documentation for Your Open-Source Library
本站链接:https://www.codesec.net/view/586423.html


1.凡CodeSecTeam转载的文章,均出自其它媒体或其他官网介绍,目的在于传递更多的信息,并不代表本站赞同其观点和其真实性负责;
2.转载的文章仅代表原创作者观点,与本站无关。其原创性以及文中陈述文字和内容未经本站证实,本站对该文以及其中全部或者部分内容、文字的真实性、完整性、及时性,不作出任何保证或承若;
3.如本站转载稿涉及版权等问题,请作者及时联系本站,我们会及时处理。
登录后可拥有收藏文章、关注作者等权限...
技术大类 技术大类 | 前端(javascript) | 评论(0) | 阅读(73)