The Perfect Documentation Platform

What the perfect documentation platform means for me?. Don't know if perfect is the right word, but there is a tool that gives me all the power I need for this purposes. And what I need?. It's hard to say in a couple of words because along the time the needs have been changing with me. But I will try to summarize some of the must features I'm not able to live without:

Include

DRY means "Don't Repeat Yourself". Sometimes while I'm documenting some stuff I realize that it's always the same block of text, for example, adding a new sftp user to a domain. Instead of copy/paste the same text all the time (you can imagine the PITA if there are typos inside and the text was copied > 50 times). It's so nice to be able to do something like:

==== Add SFTP User ====
{{page>doc:generic:add-sftp-user&noheader}}

If I want to change something I just open the add-sftp-user page and... done! in all the occurrences!. And it is even better, I can include a whole page or only a part of it, with or without the title (header):

{{page>doc:generic:add-sftp-user}}
{{page>doc:generic:add-sftp-user&noheader}}
{{page>doc:generic:add-sftp-user#subtitle-inside}}
{{page>doc:generic:add-sftp-user#subtitle-inside&noheader}}

Isn't it amazing? I couldn't find something similar outside the tool I'm using, I don't know if there are any other alternatives that can achieve something closer to this using markdown, rst or whatever, someone?.

Gallery

What are you using a gallery for?. Are we still talking about documentation?. Yes we are, I really like to write all kind of documentation, not only tech one. Sometimes I like to grab some screenshots of the Desktop, Preferences of a certain software, or some real photos of the new gadget I bought, it's nice to take a look to this kind of information after a while. How to deal with it?. Well, it's really easy when you have a Media Manager to upload the pics, then you only have to write something like this in the place you want to insert a gallery:

{{gallery>pics:gadgets:macmini:*.png }}

And, of course, you are plenty of options to play with the photos, sizes, crops.. even a lightbox gallery.

Outline / Table of Contents (TOC)

When you are writting large documents, they should be structured in sections and subsections, what I expect from a tool that tries to help me in the documentation, is the ability to automagically generate this table of contents. Most of the tools I know does it by default, nothing to say. Almost:

~~NOTOC~~

In the tool I'm using if you add this string in the end of the document, the TOC won't be generated (helpful in short documents or in pieces just created to be included in bigger documents). Amazing.

Search

When you are managing < 10 documentation files is not hard to find whatever, but once it grows up a bit the search will be a real nightmare. That's why a builtin search engine makes the difference. Judging from what I've seen out there, there are many options to connect many of the tools with other solutions like Apacle Lucene, Solr, SphinxSearch and similar, but if I'm talking about KISS, this kind of stuff is not for me (for now).

Definitely, a search engine and the ability to choose what to index are a must.

Friendly reading experience

Friendly is a really big word. For me it would mean just open the files in an editor and read the documentation, but probably that's not the definition of friendly from the point of view of the customer. The perfect tool should have something like a web frontend to properly render the syntax of the documentation.

Shortcuts to go anywhere

I'm really used to the folder/ + file(s) structure because it's what I have been using since the first time I took a keyboard. For me the documents fits perfectly in this kind of structure:

docs/
  personal/
  work/
    project1/
    project2/
      specifications.txt
      roadmap.txt
      web.txt

If I want to go to the project2 documents I can just use the terminal (cd docs/work/project2), but if I am browsing the web frontend, an index collapsable and expandable tree would be the best solution. And if I can give access to the customer with her own user to the folder of the project it would be just perfect!.

Portability

What's the ultimate purpose of write documentation? To read it. It has to be available in all possible scenarios. For me it would be ideal just to have the files and folders synced across all the devices where it's supposed to be read, and in some of them, even the requirements to launch the web frontend.

To be honest this one is the weak point of my tool. If I want to take with me the readable version of the docs I need a web server + a virtualhost pointing to the software, plus some other required operations as maintain the software, backups, etc...

In it's favour there is no database required but some times a web server is still a high price nowadays.

Tools

I have been checking some tools here and there last weeks, not because I'm not happy with my current solution, but having seen the portability problem and, on the other hand, taking in account that I really like the markdown syntax; if there was something similar but markdown based and without the requirement of maintain any piece of software, probably some efforts will have been worthwhile. But I couldn't find anyting. I've considerated:

• Jekyll
• Flask + Frozen-Flask
• MarkServ
• MkDocs
• Sphinx (not Markdown but reStructuredText)
• ReadTheDocs

But none of them reaches all the minimum viable points I've listed in this entry. So in the end I've decided just to stay where I am because - for me - I have the most appropiate tool: Dokuwiki.