Building a Documentation Site

06.05.2014 13:25Comments
KidoZen Documentation

We finally re-wrote our entire KidoZen Documentation Site from scratch. It’s something I’ve been wanting to do for a while, and now was the time. Writing a good documentation site is not easy, and here are a couple of things we learned from having to re-do ours.

Writing Documentation is Hard

…but a very good exercise. Sometimes writing conceptual articles about a product can be harder than it seems. You need to convey the Vision, and the Goals behind the product, and at the same time give a simple and clear explanation of how the Product executes on these. This exercise leads to asking fundamental questions which leads you to even better understanding of your product, and find better ways to describe it.

Choose your tools consciously

As with any other endeavour, before you even start, you should take some time to pick the right tools. Choose your tools not only based on who is writing the documentation now, but also based on who will be writing documentation in the future and how! The reason why this is so important to me, is because being a developer, we first chose to build our documentation using Jekyll. Jekyll, while pretty cool, simple and convenient for developers, it is a source of issues and complaints for non-developers. So when we re-did our documentation we chose a more friendly platform like Wordpress.

Organically grow your content

Our first documentation site was simple and clean at the beginning. We took the approach of growing the content of our site organically. What does this mean? We did not build our entire content in advanced. We were doing this as we went. Sometimes as a reaction of our customers doing questions, and sometimes as we kept on adding features. The good thing about this approach, is that you are keeping the content at a minimum, and that helps make your site easier to navigate and to understand. The bad thing about this, is that sometimes it’s not so easy to find the right place for the new content. And here is where you might need to step back, and re-organize your content. That’s where the next section comes in.

Take the time to architect your content

Just as in Novel writing (not that I am a writer of any kind), the best way to put all the pieces together might be to enumerate your content, see what are all the things you want to tell, and then do some good old “Cardboard” to move pieces of content around. I found this part to be particularly important to get right, because I got it wrong a couple of times. Having tools like Scrivener, might make the process much more pleasant!

Add a Search Box!

I can’t believe we actually missed this one on our first version of the documentation site. Surely the site being super small and straight forward, had something to do with it. However as the site grew bigger, things were not as straight forward to find, and as soon as we added the Search Box on the site, we realised how easier is to just shortcut through the search, instead of going through all our genius navigation (we only knew about) to find stuff.

Have Fun

Documentation might strike as a very boring thing to do. I think it is important that everybody helps write documentation, and try to make the process as easy and painless as possible. For doing that I think it’s important to understand not just WHY we do it, but why we WANT to do it. As soon as you find the right ending for “I really want to write this documentation piece because I ….” it all starts being so much easier and even fun!

comments powered by Disqus