Recommendations appreciated.

Disclaimer: Most of these make little sense in an Internet medium anyway.

  • An index. An index simply lists the terms and topics discussed in a document, along with the pages they are listed on.
  • A glossary. Could be as simple as a CSV file of terms and definitions, or as complex as a whole extra glossary/ folder.
  • Related: A “Acronyms and Abbreviations” section. Even moreso than the last, this could be a simple CSV.
  • A built-in site-wide search function. Word gets around this by having everything open at once.
  • A list of tables. Huge if you want your dead-trees books to match your shiny new website.
  • A list of figures. Ditto.
  • A list of referenced external documents. CSV! Say it with me!

The reason I compiled this list was because I decided to investigate whether I could use Hugo at work to generate our client-facing documentation. Currently we are using an unholy combination of Word and Confluence, and I figured that the magic of Git might help us keep our docs updated in a more sane way.

Then as soon as I sat down and actually tried for 15 minutes I realized just how many reasons there are why that won’t work for us. Not one of the above is negotiable, alas.