In late 2013, I was tasked with being the lead person for documentation on a couple of products under WebDevStudios’ wing. The first one, AppPresser, was definitely going to need documentation. Turning WordPress powered websites into native-like applications that can be added to app stores was going to be a hot topic and any information a developer could get on it would be essential. The other product was revamped documentation for the StartBox Framework and all of the work we have going on there.

I needed to find a way to make management of all of the content as easy as possible, and if we were lucky, as easy for others to contribute to as possible as well. My ideal desires for this management had two key components: Markdown Syntax support and be version-controllable. After asking around for part of a day, I was pointed to Pico, a flat-file CMS. What they mean by flat-file is that there is no database. All of the content is powered by individual files to make up the content of the website. However, it keeps the content and presentation separate. It still offers plugins and themes like I am already familiar with from years of WordPress experience. As silly as it may sound to power documentation for WordPress plugins/frameworks with a completely separate CMS, my mind instantly found it making a lot of sense and an acceptable deviation.

With this solution in place in my mind, I went ahead and downloaded it, and began to get familiar with how it worked. Its setup is pretty simple. you have your base folder that you put on your domain, and inside that is a /content/ directory that holds all of your markdown files that make up the actual page content. Within each something.md file, you type up and markdown format your content. However, you also need to provide a small “meta” comment area at the start of each file for it to be recognized by Pico. The bare minimum that you need to provide is a title, like so.

/*
Title: My Page
*/

for it to get recognized. Out of the box, it provides a few extra meta fields like “Author”, “Date”, and “Description” that can all be utilized within a theme to format the output and display to the users. They have also made these meta fields extensible so that you can add custom data as well. Through already created plugins, I added “Last Edited” meta for both AppPresser and StartBox files for the sake of knowing content “freshness”.

Due to the nature of documentation, you do not want every single file getting a place in the navigation, it’s better to limit to specific “sections” depending on your planned information hierarchy. I tried out a handful of different plugins to help achieve this, but none were really working the way I needed, so I had to roll up my sleeves and code my own. In short, I had to set up some config variables that contained which “pages” I wanted shown, and some that contained all that I did not want. Thankfully, hierarchy and child files were excluded as well, so I just had to worry about excluding the highest parent directory instead of every single file inside. All that was left was looping through all of the calculated pages determined by Pico, and include/exclude appropriately. May not be the most graceful solution, but it is getting the job done.

The rest was simply adding some useful plugins like “table of contents”, as well as altering the specified theme to fit the associated product website. You can see the source code as well as the wiki with links to user-contributed plugins, over at their GitHub profile.

With the lack of a database to worry about, you can easily put your entire Pico install into a Git repository and allow users or contributors to make pull requests. If you wish to not let them have access to the base install, and just want them to see the /contents/ directory, you can simply put that into the repo and have it deploy to inside the Pico base directory on the actual website. With pull requests, you can have a level of control and moderation before blindly having every single change go live right away like a wiki would offer.

All in all, I have to say my experience with Pico has been a pleasant one. Like with anything, there is a bit of a learning curve, but Pico is pretty simple and powerful with that. I definitely didn’t go over all of the details that I could have. However, if you want a pretty simple setup for a topic like documentation, without messing around with a full database application or a wiki, Pico is definitely something to consider. Feel free to ask me anything about the whole process, and I’ll answer the best I can.