The Importance of Documentation for Web Developers
https://www.hongkiat.com/blog/why-documentation-essential/
In the development realm of mobile, web, and desktop apps or JavaScript libraries, documentation plays an important role in determining the app’s success. But if you have ever done documentation, you’d agree with me that it is pretty much the least favorite thing for developers to do.
Unlike writing code (which is what developers signed up to do), documentation has to be easily digested by everyone. Technically, we have to translate a machine language (code) into a language that is understandable to humans, which is tougher than it sounds.
Although it can be a real burdensome, writing the documentation is important and will deliver advantages for your users, your colleagues, and especially yourself.Learning Programming: 10 Misconceptions That Are Not True
Good Documentation Helps Users
Documentation helps the reader understand how a code works, obviously. But many developers make the mistake of assuming that the users of the software will be proficient.
Hence, the documentation may be thin material, skipping a lot of the essentials it should have contained from the beginning. If you are savvy in the language, you can figure things out on your own initiative; if you are not, then you are lost.
Documentation intended for users usually consists of practical use or the “how-to”. The rule of thumb when creating documentation for general users is that it should be clear-cut. Using human-friendly words is preferable to technical terms or jargon. Real use examples will also be greatly appreciated.
A good layout design would also really help users scan through each section of the documentation without eye-strain. A few good examples (aka my favorites) are documentation for Bootstrap and WordPress‘ “First Steps With WordPress”.
It helps fellow developers
Good Documentation Helps Users
Documentation helps the reader understand how a code works, obviously. But many developers make the mistake of assuming that the users of the software will be proficient.
Hence, the documentation may be thin material, skipping a lot of the essentials it should have contained from the beginning. If you are savvy in the language, you can figure things out on your own initiative; if you are not, then you are lost.
Documentation intended for users usually consists of practical use or the “how-to”. The rule of thumb when creating documentation for general users is that it should be clear-cut. Using human-friendly words is preferable to technical terms or jargon. Real use examples will also be greatly appreciated.
A good layout design would also really help users scan through each section of the documentation without eye-strain. A few good examples (aka my favorites) are documentation for Bootstrap and WordPress‘ “First Steps With WordPress”.
It helps fellow developers
Each developer will have his own coding style. But, when it comes to working in a team, we will often have to share codes with other teammates. So it is essential to have a consensus on a standard to keep everyone on the same page. A properly written documentation would be the reference the team needs
But unlike end-user documentation, this documentation typically describes technical procedures like the code-naming convention, showing how particular pages should be constructed, and how the API works along with the code examples. Often we would also have to write the documentation inline with the code (known as the comments) to describe what the code is doing.
In addition, in the case where you have new members joining your team later, this documentation could be a time-effective way to train them, so you don’t have to give them a 1-on-1 run down on the code.
It also helps the coder himself
The funny thing about coding is that sometimes even the developers themselves do not comprehend the code that they have written. This is particularly true in cases where the codes have been left untouched for months or even years.
A sudden need to revisit the codes for one reason or another would leave one wondering what was going on in their minds when they wrote these codes. Don’t be surprised: I’ve been in this situation before. This is precisely when I wished I had documented my code properly.
By documenting your codes, you will be able to get to the bottom of your codes quickly and without frustration, saving you a lot of your time that can be spent on getting the changes done.
What makes for good documentation?
There are several factors that help in building a good piece of documentation. Some of the most important ones are as follows:
1. Never assume
Don’t assume that your users know what you know as well as what they want to know. It is always better to start from the very beginning regardless of the users’ proficiency level.
If you built a jQuery plugin, for example, you may take inspiration from SlickJS‘s documentation. It shows how to structure the HTML, where to put the CSS and the JavaScript, how to initialize the jQuery plugin at its most basic level, and even shows the complete final markup after adding all these stuff, which is something obvious.
The bottom line is that the documentation is written with the thought process of a user, not a developer. Approaching your own documentation this way will give you a better perspective in organizing your own piece.
2. Follow the standard
In adding documentation that goes inline with the code, use the standard expected of the language. It is always a good idea to describe each function, the variables, as well as the value returned by the function. Here is an example of good inline documentation for PHP.
| 123456789101112131415 | /** * Adds custom classes to the array of body classes. * * @param array $classes Classes for the body element. * @return array */function body_classes( $classes ) { // Adds a class of group-blog to blogs with more than 1 published author. if ( is_multi_author() ) { $classes[] = 'group-blog'; } return $classes;}add_filter( 'body_class', 'body_classes' ); |
The following are a few references for formatting inline documentation with best practices in PHP, JavaScript and CSS:
- PHP: PHP Documentation Standard for WordPress
- JavaScript: UseJSDoc
- CSS: CSSDoc
If you are using SublimeText I would suggest to install DocBlockr that will cleverly pre-populate your code with inline documentation.Coding Standards For WordPress [Guide]
Coding Standards For WordPress [Guide]
The reason that we have coding standards at all (not just for WordPress) is to create a familiar…Read more
3. Graphical elements
Use graphical elements, they speak better than text. These media come in useful, particularly if you build software with graphical interface. You can add pointing elements like arrows, circle, or anything that may help users to figure out where to go to accomplish the steps, without guesswork.
The following is an example from the Tower app where you can draw inspiration from. They efficiently explain what how version control works in a pleasing way that makes it more understandable than using plain text command lines.
4. Sectioning
You may consider wrapping a few things in the documentation within bulleted lists and tables as this makes longer content easier to scan and read for users.
Add a table of content and split the documentation in easily digestible sections, yet keeping each section relevant with what comes next. Keep it short and straightforward. Below is an example of nicely organized documentation in Facebook. The table of contents takes us where we want to jump to in a click.
5. Revise and Update
Lastly, review the documentation for mistakes and revise when necessary or and whenever there are significant changes to the product, software, or library. Your documentation would be of no use to anyone if not regularly updated alongside your product.
在移动、Web 和桌面应用或 JavaScript 库的开发领域中，文档在应用的成功之路上扮演着非常重要的角色。但如果你曾经编写过文档，就肯定会同意我的看法：编写文档是开发人员最不喜欢做的事情之一。
与编写代码（这是开发人员的本职工作）不同，文档必须能被所有人轻松理解（这里的所有人不仅是指开发人员，也包括缺乏技术背景的一般人）。从技术上讲，我们必须将机器语言（代码）翻译成普通人都可以理解的语言，这种事情说起来容易做起来却很难。
尽管这件事情可能会给你带来很大的负担，但是编写文档是很重要的环节，并且可以为你的用户、你的同事，尤其是你自己带来诸多好处。
好的文档可以帮助用户
显然，文档可以帮助读者 理解代码的工作原理。但是许多开发人员有着错误的认识，那就是他们认为软件的用户都是编程高手。在这样的假设下，他们编写的文档可能只是薄薄的几页纸，从头到尾跳过了文档本应该包含的许多要点。如果你精通编程语言，那么遇到问题还可以自己找出解决办法。如果你并没有那么专业，那么看文档时很容易就会迷失方向。
供用户使用的文档通常包括使用实践或“操作方法”的内容。为一般用户创建文档时，经验法则是 文档应该清晰直观。使用普通人也容易理解的词汇要比使用技术术语或专业习语更合适。软件的实际应用示例也是非常受用户欢迎的。
良好的文档布局设计还可以真正帮助用户轻松浏览文档的各部分内容。在这方面一些很好的例子包括 Bootstrap 的文档，和 WordPress 的“WordPress 的第一步”文档，它们也都是我最喜欢的榜样。
好的文档可以帮助其他开发人员
每位开发人员都有自己的代码风格。但在团队合作中，我们经常需要与其他同事共享代码。因此大家有必要 达成共识，形成一套标准，以使所有人保持一致。精心编写的书面文档会是团队必要的参考。
但与最终用户文档不同，这类文档通常会描述代码命名约定之类的技术流程，展示开发人员应如何构造特定页面，以及 API 如何工作，外加一些代码示例。通常，我们还必须在代码内编写文档（称为注释），以描述所注释代码的作用。
此外，如果以后有新成员加入团队，这类文档可以是培训他们的一种省时有效的方法，这样你就不必为新人一对一地讲解代码了。
好的文档也可以帮助开发人员自己
关于编程的有趣之处在于，有时 甚至开发人员自己也不理解他们编写的代码。尤其是当开发人员几个月甚至几年都没再碰过自己写过的代码时，他们突然回来看自己的作品会感到十分陌生。
如果出于某种原因，开发人员需要重新审阅以前的代码，他们往往会怀疑自己在编写这些代码时到底在想些什么。别惊讶：我以前就曾遇到过这种情况。在这种情况下，我肯定会希望自己给代码写下了良好的文档。
给你的代码写好文档的话，你就能够快速深入到代码的底层，不会有那么多疑惑，从而节省许多时间。省下来的这些时间可以拿来完成更改工作。
好的文档有哪些特性？
有几个因素可以帮助你构建出良好的文档。其中一些最重要的因素如下：
1. 永远不要假设
不要以为你知道的东西用户也知道，或者他们很清楚自己应该了解的内容。无论用户的熟练程度如何，总是 从头开始解释各种事情 是更好的选择。
例如，如果你构建了一个 jQuery 插件，则可能会从 SlickJS 的文档中汲取灵感。它介绍了如何构造 HTML、放置 CSS 和 JavaScript 的位置、从头开始讲解如何初始化 jQuery 插件，甚至还展示了添加所有这些内容后的完整最终标记，所有东西都写得清清楚楚。
最重要的是，文档应该是根据用户而不是开发人员的思考过程来编写的。以这种方式处理你自己的文档，将为你提供一个更好的视角来组织自己的代码。
2. 遵守标准
在添加与代码内联的文档时，请使用 代码编程语言所期望的标准。 我们应该总是解释每个函数、变量以及函数返回的值都是什么意思。下面是一个很好的 PHP 内联文档示例。
/**
* Adds custom classes to the array of body classes.
*
* @param array $classes Classes for the body element.
* @return array
*/
function body_classes( $classes ) {
// Adds a class of group-blog to blogs with more than 1 published author.
if ( is_multi_author() ) {
$classes[] = 'group-blog';
}
return $classes;
}
add_filter( 'body_class', 'body_classes' );
以下是使用 PHP、JavaScript 和 CSS 的最佳实践来格式化内联文档的一些参考：
如果你使用的是 SublimeText，我建议你安装 DocBlockr，它将用内联文档巧妙地预填充你的代码。
3. 图形元素
文档中应该多用图形元素，它们比文本更直观。这些媒介很有用，特别是当你使用图形界面构建软件时。你可以添加指向性元素，例如箭头、圆圈或 任何可以帮助用户直观地弄清楚如何完成这些步骤的元素。
以下是 Tower 应用中的示例，你可以从中汲取灵感。它们很好地解释了如何用优雅的方式来做版本控制工作，比纯文本命令行更容易理解。
4. 分区
你可以考虑将文档中的一些内容包装在项目符号列表和表格中，因为这样可以让用户更容易浏览较长的内容，更方便快速定位。
添加目录，并将文档拆分为一些容易理解的部分，同时要让各个部分与接下来的内容保持关联。内容应该简短明了。以下是 Facebook 中一份组织良好的文档示例。
我们可以点击目录元素，直接跳转到对应内容。
5. 修订和更新
最后，文档写好后要仔细查看文档中是否有错误，并在必要时，或在产品、软件或库发生重大更改时修订文档。如果不随产品一起定期更新，那么你的文档对任何人都是没用的。