Documentation with Markdown

Several times, I’ve mentioned that I’m a huge fan of markdown – I use it to write emails, I dig that that’s how GitHub handles README files, I use minor variations of it in my blogging, and I’ve got a favorite app for it.

Thanks to a heads up from one of my partners, I can now write documentation with markdown.

Here’s the thing: I’ve mentioned that I’m a huge advocate for code comments – I think it’s better to go a little overboard for the sake of clarity than not, especially in open source projects.

And sure, PHP DocBlocks and tools like PHPDocumentor make it relatively easy to generate documentation, but documentation like that is best suited for other developers. It’s not exactly end-user friendly, right?

In that case, you’re talking about writing a manual.

Documentation For Users

When it comes to writing documentation for users, there’s a variety of things to consider:

  • How easy is it for them to discover the documentation?
  • Is it written in language that they understand?
  • Is it kept up-to-date with each release?

On top of that, there are a number of tools for writing said manual.

Up to this point, my team and I have generally stuck with using WordPress and some light customizations of a theme.

The Standard Theme User Manual on WordPress

The Standard Theme User Manual on WordPress

No, it’s nothing glamorous and it’s a relatively simple solution, but it gets the job done, it’s easy to maintain, and it’s linked up from within the theme admin.

But this still requires a little bit of initial overhead – namely, setting up the server, database, WordPress installation, and so on.

Documentation with Markdown

Enter Flatdoc.

Flatdoc for Documentation with Markdown

Flatdoc for Documentation with Markdown

In short, Flatdoc is an open source project for writing documentation in Markdown.

I love the way it works:

  • Write the documentation using markdown
  • Include a JavaScript file in a page (and direct the JavaScript to the markdown file)
  • Provide some options for theme customization
  • Profit!

To be fair, I don’t think this solution is right for everyone. After all, if you’ve got someone on your team who’s in the business of writing documentation for other projects, they have their own tools, and/or they have a different way of doing things, then go for it.

After all, markdown is still one of those languages that leans in the direction of developers.

But that’s exactly it: If you’re a developer who wants to include more documentation than that for fellow developers, and you’re looking for an easy way to do it such that you can write it in markdown format and then have a tool generate a good looking page (or set of pages for you), then Flatdoc’s the way to go.

I’m aiming to begin releasing a couple of projects with documentation using Flatdoc. Eager to see how it goes.


Join the conversation! 9 Comments

  1. Tom, that FlatDoc looks both way useful and very inspiring. Love that side-by-side layout.

    Keeping documentation readable, relevant and relatable is a continual challenge, and one that usually suffers as development is more fun and support takes precedence (sadly ironic of course, as good docs reduce support).

    With all the great posts and great information here, sometimes I wonder how you get any “real work” done, you must be an amazing time manager. Would love to see a post on what your days and week look like and how you stay on task.

    • With all the great posts and great information here, sometimes I wonder how you get any “real work” done, you must be an amazing time manager. Would love to see a post on what your days and week look like and how you stay on task.

      I’ve been blogging for a quite a while now and, in my opinion, it’s a matter of having a backlog of ideas for content (which come easier the more you write), and – like you said – managing your time.

      I’m covering stuff like that in this series of posts.

  2. Nice to know about Flatdoc. I made a simple bootstrap based WordPress theme for my documentation. I wish I knew it sooner about flatdoc :D

  3. I did something similar a few months back, but I have to say yours is much nicer, I love the plug-in mechanism for fetching the files from various sources.

  4. I just found your post and Flatdoc looks really good. I just want to mention another great documentation project which uses Markdown. -> ( I used daux in a few projects and it works similar to flatdoc :)

    Yeah – I love Markdown, too ;)

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.