Our Approach to Documentation

FooBot Get's Carded

As we announced recently, we just pushed our new documentation site live. I’m pretty excited about it because I think it will help our users out a ton. And that’s pretty much my job: Helping users out. So if they can get the help they need without submitting a support ticket, awesome! I get to vacation and still get paid ;-)

All kidding aside, our new Docs site is all that and a bag of chips (I know, no one says that anymore, humor an old guy). I wanted to write this post to do just a few things:

  1. Give you some insight into how we developed the site
  2. Give a shout out on some of the tools we used to build the site. And…
  3. Ask you for your feedback on developing good Documentation for software.

Our Internal Dialogue

Brad Vincent and I chatted over a long period of time about how to set up the documenation in a way that is useful for both end users (who don’t do code at all) and developers (who want to build extensions off our stuff).

As you know, I’m the support guy, and I’m interested in taking vacations, so all I wanted the Docs site to do was to answer all your questions in advance. For me, that meant there needed to be some detailed walkthroughs and demos. For me, that meant that the user experience was supreme. Users needed to be able to navigate to exactly the feature or function they are looking to accomplish on their site, go through a walkthrough and…success!

Brad, on the other hand, is a javascript demi-god, and comes at everything from a super experienced and educated technical perspective. In his perspective, documentation is about detailing all the hooks, filters, and potential usage of the scripts for developers.

And that’s 100% correct.

If you cruise through the WordPress Codex, you’ll see that is exactly what the WordPress Core Development team envisions for their documentation as well. So that’s absolutely the right and standard way to go.

So in Brad’s mind, users needed to be able to go to the docs site and find all the technical details of the code and be shown use cases of how to implement that code on their site.

footable-docs-screenshot

FooTable Documentation

Both of us had in mind Brad’s already excellent documentation for FooTable jQuery. If you haven’t seen that in action, just head over there for some oooos and ahhhhhs.

Another factor in place is that we wanted to have a public “playground”, a place where we could test out new features and edge-case uses of our plugins without putting fooplugins.com at risk at all.

The end result of all those desires, dialogues, and developments was that we decided to put all the walkthroughs, demos, and code examples in the documentation site.

Then, we took our already existing “Showcase” site and re-purposed that to be the public “playground” where we test out edge-use plugins, throw various plugins all on the same field and watch them duke it out. That’s still in development, but it’ll be fun to watch it grow and evolve as we continue to develop our plugins.

Tools We Used to Make it Happen

For the showcase site, we just used the plain vanilla twentythirteen theme because it’s just the canvas behind all that the plugins are doing there. But the docs site needed a much more robust environment in order to categorize all the documentation in a way that made sense in the navigation, was easily searchable, and could allow all the plugins to be installed on the same server without all hell breaking loose.

The first thing we did was land on using the WP Knowledge Base theme by Swashata.

There are plugins out there for developing documentation (and we’re still toying with building out own), but in this case, we knew the whole site would only be documentation so a theme approach would work just as well.

Further, Knowledge Base is really well structured and leverages WordPress’s Categories in really unique and powerful ways. The categorization, built in bootstrap styles and icons, and the responsiveness made this a slam dunk for us.

Plugin Organizer Screenshot

Plugin Organizer in Action

The next thing we did was implement the Plugin Organizer. This is a really powerful and useful plugin which allows you to enable or disable plugins per page/post or even globally.

This for us was a must.

Of course, by this time next year we want to have HUNDREDS of plugins on there (well… that’s what we want ), so even if we knew with certainty that they all would play nice with each other, we certainly didn’t want them loading all 100+ of them on every page of the site. That’s insanity. This plugin has become a must-have in my personal development arsenal, and it works great on the Docs site as well.

But Is this REALLY Documentation, or Just Demos?

So this is the part I’d love to get your input and feedback on.

We’re definitely not the first to do documentation this way. There are lots of other stellar plugin marketplaces that do documentation really well (and others who… well…). But this question is also a bit of a red herring.

Sure, enterprise level developers need to follow really strict documentation rules so that dozens of developers can contribute to the documentation and everything remains consistent and navigable. But a “document” like that is basically completely useless to a Photography blogger who just wants their images to “pop” on the screen with FooBox.

Nevertheless, it’s this question, or this realm of development that pushed us to make the decisions we did for our docs site.

It’s our hope that it is extremely valuable to our users, and that we develop it further and document all of our plugins there, that the usability and navigability of it will always remain.

Now it’s your turn. Post some excellent examples of documentation in the comments. Tell us what you think of our approach, or the site itself. Or just give us your take on what it means to do documentation well.

This post was written by
Matt is our "Solutions Manager". When you contact us, he's your guy. Matt has been building websites for 10 years, tweaking and hacking at WordPress for 3 years, and generally being helpful since birth.

5 Comments on "Our Approach to Documentation"

  • Theresa

    As someone who is hearing impaired, please give me written documentation (that’s been proofread). Especially if your Screenr video is not well-closed captioned and English isn’t your first language. If I knew enough about your code/theme/plugin to not need documentation, I probably could have created it myself.

    • Hi Theresa, it seems like you are responding to documentation you’ve encountered in the past. That makes a lot of sense. We don’t use videos that much in our documentation (really only as demonstrations since FooBox supports video), but I will make a note of keeping closed captioning in mind for any future videos we do that are instructional in any way. Thanks for the input.

      • Theresa

        Yes, I was giving you suggestions based on my previous experience with stuff that WASN’T yours.

  • IMO there are two types of documentation, Technical Documentation and User Documentation. There’s overlap at times but for the most part they’re separate worlds.

    My favourite example of docs-done-right is the MailChimp KB for users: http://kb.mailchimp.com/home and API Docs for developers: http://apidocs.mailchimp.com/

    The experience is very different between the two. The KB focuses on “How do I do this?” answers, while the API docs focus on “How does this work?”

    One is for education, the other is for reference.

    • Yep, you’re touching on exactly the conversation Brad and I had. But the question is what is the benefit of them being separated? Don’t you think having the overlap allows for beginning users to be exposed to more material that could encourage their learning code in the long run?

Leave Your Comment