A common annoyance I experience when interacting with a new programming language is online-only documentation.

Most [programming] languages these days do not come with offline documentation by default, which really annoys me since it’s benefits are plenty and cons are virtually none.

Documentation should always be available offline and in command line form, online copies could exist. But the default must be offline, for the following reasons:

  1. It’s always available
  2. It’s easier to reach
  3. It’s fast
  4. Format your docs however you like
  5. Powerful filters via unix pipes

Take for example php, php has no offline documentation. AFAIK it does not have it as a command line utility or as a gui, which is really disappointing. You have to get a copy of their website offline and view it via your browser, which to be frank is too much effort.

The fault does not lie with php only, the web frontend stack(html, css, js) do not include offline documentation by default. I mean there is :

  • autocompletion
  • color picker
  • performance profile
  • syntax highlighting
  • dark theme for said syntax highlighting
  • source viewer
  • [seo, pwa, best practices, accesibility] analysis tool

… but bundling documentation to an already big(300MB+) program

Documentation is the utmost important thing in a language, you cannot learn a language without documentation. And having easily filterable & readily available documentation increases the programmer’s understanding of the language.

Offline documentation in command utilities allow for very powerful and precise results, you could chain multiple commands to get the result you want. Or you could make a better frontend to the documentation tool, because at the end of the day it’s text.

Contrast this to a google search that rarely yield good documentation, and even if it does it’ll take a minute or two to fetch the results and highlight the wanted result, while command line utilities will take a sec or two.

While losing a minute or two is not so costly, losing focus is. Web Browsers are like quicksand for focus, you look up documentation and don’t close a window. After 15 minutes you’re watching a turkish kid saying börger.

As example of excellent offline documentation command line utility, check out golang. Golang has very excellent command line utilities with automatic documentation both in the terminal and as a web server. As showcased down below:

# view the list of [methods, constants, structures] in the 'fmt' library
go doc fmt 
# search for method Println
# this is using grep
go doc fmt | grep Println
# view the fmt Println description and parameter
go doc fmt.Println
# view source for Println method
# sometimes strange behaivour is not documented
go doc -src fmt.Println
# view data structure Client from net/http library
go doc net/http Client

Note how precise these are, and how fast you get these results. Compare this to searching via google, you’ll have to click multiple links to get what you want. Without any possibility with filtering without viewing the output first, and very weak filtering at that.

If you still are not convinced with my argument, try out offline documentation. Worst case scenario you wast a couple of minutes or hours, best case you increase productivity in software development.