Wiki’s are a great technology. Well for some things. For documenting systems I am not convinced. Some problems:
- All the old stuff that piles up. Nobody ever deletes anything.
- Versions. If you have maintenance versions as well as active development etc. how do you update, merge and maintain several versions?
- Historical snapshots. What was the state of the entire documentation at the time of release?
Is is possible to solve with a Wiki? Yes. Does Atlassian do it? Yes. Does it work for us? Nope. Maybe we lack discipline but it’s not working. Our tries at fixing this has only seemed like band aids or placebos to the real problem. I want my documentation released, versioned, branched and merged with my code!
I was already writing some stuff in my README files as Markdown, so I decided to give it a spin. And it works quite nicely. 🙂
Hoping I will be able to replace system doc in the wiki with it, but that will take more testing. Just some short notes on making it work in Subversion.
Making it local
Flatdoc doesn’t really need installing, especially if you run it with a project on Github. But because we have network zones, and I wanted to host it directly off our SVN-server (over HTTP) I downloaded everything:
mv template README.html
mkdir flatdoc && cd flatdoc
So now you have a README.html with a subdirectory called
flatdoc/ with all the scripts and styles.
Enabling SubVersion hosting
To enable the SubVersion server to serve the files you need to set the mime types. But first, if you have not; add them to SubVersion:
svn add README.html flatdoc
svn commit -m "Installed Flatdoc"
Then set the mime types:
svn propset svn:mime-type text/html README.html
svn propset svn:mime-type text/css flatdoc/*.css
Hooking in your Markdown file
Edit the template file you downloaded into README.html.
<!-- Flatdoc -->
<!-- Flatdoc theme -->
<link href='./flatdoc/style.css' rel='stylesheet' type="text/css"/>
That should be it. 🙂 Commit to SubVersion and access through HTTP.
Note about testing and local rendering
Because of security restrictions in your Browser, local testing will not work. You will get an origin-error when trying to read the Markdown file. You can either disable that security check in your browser, or use some kind of Markdown preview locally. The Markdown preview for Sublime Text works pretty well. 🙂