• Define the audience
• Define the purpose
• Define the assumptions
• Provide a way to contact the author
• Provide a way to ask additional questions

Question

What do you need to know to write good documentation?

Answer

You need to know who your audience is. You need to know what they should know so that you can make assumptions about their knowledge. You should also be able to tell what they won't know. It is mainly this lack of knowledge that you need to fill when you write your documentation.

Once you have established who your audience is, you should state it clearly. This way, readers will be able to determine if they identify or not with the target audience, which can help them better frame how to read the documentation.

The purpose of documentation should be clear. Is it to describe a specific use case, provide a getting started guide, answer specific questions regarding functionalities?

You need to state explicitly what you will cover and not cover in the documentation. Readers may start reading your document which contains assumptions about their knowledge, but if they do not have this knowledge, they should know where to acquire it.

It should be easy for readers to know where to reach the author of the documentation or people knowledgeable enough to guide them to the right people.

References

• https://www.divio.com/blog/documentation/
• https://www.sohamkamani.com/blog/how-to-write-good-documentation/

Problem

I have movie ratings that I would like to import into IMDb. I also happen to know PHP. How can I do that?

Solution

In 2013 I wrote IMDb ratings importer for the purpose of importing ratings I had created in another system (Rotten Tomatoes). I wanted to import my ratings into IMDb so that I could use their statistics reporting tools, which let you see your distribution of ratings and the distribution of the release year of the movies you've seen. A friend of mine also had his bot send a message to our discussion channel whenever one of us would update their ratings after watching a movie.

The library is pretty straightforward. It expects you to provide it with a string that uniquely identifies your cookie on the server side. With an array of all the titles and ratings that you have, you can submit those ratings and the library's importer will take care of calling IMDb by finding the closest movie title and assigning it the desired rating.

References

• https://github.com/tomzx/imdb-importer

Question

How can you onboard users to use your library as fast as possible?

Answer

You need to make it as frictionless as possible for them to use your library.

First, they need to know the value proposition of the library. They need to know why they should use your library and not find another one available online. It needs to be convincing and to touch on the tasks they need to accomplish. The closer your vocabulary is to theirs, the easier it will be.

Second, the installation process needs to be as painless as possible. If you use a language with a package manager, give instructions on how to install your package using the package manager. If there are multiple popular package managers for the language in which the package was written, make sure to cover the most used ones.

Third, when users do not understand how to do certain tasks using your library (when it is in its early stage of development), take note of those questions, especially the wording. You want to capture what they were trying to do, how they described what they wanted to do, and why they were trying to do it. With this information in hand it should be easy for you to determine whether your library supports (or should support) the use case they tried to accomplish. If your library is not going to support the use case, make sure to indicate it early in the documentation so that users do not have the wrong expectation that your library will help them with this use case.

Finally, try to learn as much from your users as possible. Try to understand what it is they are trying to accomplish and whether it is valuable to most of them if you were to support new use cases. If you can document the most common use cases so that they can read the steps they'll have to go through, it will be simpler for them to evaluate the process before going through it.

Problem

I use Visual Studio Code as my main editor and I am on Windows 7. I like to use emojis but those aren't properly rendered under Windows 7. Can I have pretty emojis in Visual Studio Code somehow?

Solution

I developed an extension in 2018 called Emoji which uses EmojiOne emojis to replace their non rendered equivalent in Visual Studio Code.

To do this, the extension makes use of the createTextEditorDecorationType method available on the window object in order to inject CSS that adds a background image where the text emoji would be rendered.

The extension listens to two events to determine in which editor it needs to do the replacement: window.onDidChangeActiveTextEditor and workspace.onDidChangeTextDocument. In the first case we update the editor that is now the active one, in the second, we update the active document when the text content changed.

Demo

Without the extension (before)

With the extension (after)

Reference

• Visual Studio Marketplace - Emoji extension
• Github repository - Emoji extension