This project is a continuation of Stack Overflow Documentation, which ended in August 2017.

The intent is to preserve that work and improve upon it.

This project is collaborative. All documentation is released under Creative Commons BY-SA license and hosted on GitHub. Please do contribute!

Guiding principles behind Essential Books

• driven by examples
• not limited in size like a traditinal book
• articles are cross-linked
• search friendly

Driven by examples

Show, don't tell.

Not limited in size

A traditional book is limited by physical size, number of pages. This limits how much information it can have.

We don't have such constraints so there's no limit to how much useful information we can add.

Documenting popular libraries, adding step-by-step tutorials for specific tasks. Everything is in scope.

Search friendly

A search bar at the top allows quick navigation to a topic of interest.

Instead of scanning table of contents, you can type the topic you're interested in.

Halibut: yet another free document preparation system
Halibut is a documentation production system, with elements similar to TeX, debiandoc-sgml, TeXinfo, and others. It is primarily targeted at people producing software manuals.

What does it do?
Halibut reads documentation source in a single input format, and produces multiple output formats containing the same text. The supported output formats are:

• Plain ASCII text
• HTML
• PDF
• PostScript
• Unix man pages
• Unix info, generated directly as .info files rather than .texi sources
• Windows HTML Help (.CHM files), generated directly without needing a separate help compiler.
• Windows WinHelp (old-style .HLP files), also generated directly.
• Other notable features include:
  • Hypertext cross-references are ubiquitous where possible. In particular, the HTML and PDF output both have hyperlinks in every reference between sections, and throughout the index and contents sections. (It seems daft to me that so many PDF documents fail to have this; it's one of the most useful features of PDF.)
  • Support for international characters via Unicode, with the ability to fall back to an alternative representation. For example, you can write \u00F6{oe}, and in output formats that support it you will see ‘ö’ whereas in those that don't you will see ‘oe’.
  • Comprehensive indexing support. Indexing is easy in the simple case: as you write the manual, you just wrap a word or two in \i{this wrapper}, and those words will appear in the index.
  • More complex indexing is also supported, such as
    adding references to things you never explicitly said
    rewriting the appearance of index entries for a consistent style
    duplicating index entries to several places because you don't know which concept they'll be looked up under
    merging references to several things into one combined list.
  • Portability. The Halibut source code is portable ANSI C (apart from a dependency on having at least a 32-bit platform), so it should run without change on Unix, Windows, BeOS, MacOS, VMS, or whatever other (non-16-bit) OS you fancy. (Well, you might have trouble outputting PDF under VMS, due to file typing issues. I dunno.)
  • Configurability. Each output format supplies configuration directives, so it is easy to tailor the HTML output (say) to contain a standard header with links to other parts of a site, or to use a style sheet, or whatever.

However hard you work on documentation, it won't work for your software - unless you do it the right way.

   There is a secret that needs to be understood in order to write good software documentation: there isn’t one thing called documentation, there are four. 

• They are: tutorials, how-to guides, explanation and technical reference. They represent four different purposes or functions, and require four different approaches to their creation. Understanding the implications of this will help improve most software documentation - often immensely.

It doesn’t matter how good your software is, because if the documentation is not good enough, people will not use it.

Even if for some reason they have to use it because they have no choice, without good documentation, they won’t use it effectively or the way you’d like them to.

Nearly everyone understands this. Nearly everyone knows that that they need good documentation, and most people try to create good documentation.

And most people fail.

Usually, it’s not because they don’t try hard enough. Usually, it’s because they are not doing it the right way.

In this article I will explain how you can make your documentation better, not by working harder at it, but by doing it the right way. The right way is the easier way - easier to write, and easier to maintain.

There are some very simple principles that govern documentation that are very rarely if ever spelled out. They seem to be a secret, though they shouldn’t be.

Madoko is a fast markdown processor for writing professional articles, books, manuals, webpages and presentations, with a focus on simplicity and plain text readability.

With Madoko you can write complex documents completely in markdown and get beautiful PDF and HTML output.