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.
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.
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.
Leave a Reply
You must be logged in to post a comment.