Skip to main content

Walkception — documenting WalkHub with Walkthroughs

Senior Technical Writer
Oct 07, 2014

WalkHub’s documentation is a mix of a traditional user guide and interactive Walkthroughs. In this showcase we tell you more about why we believe WalkHub is a great tool for building documentation for products that are trying to grow and engage a community.

The client: the WalkHub community

From day 1 we have been designing WalkHub to make it a tool for collaboration and sharing. Coming from the Drupal community, we envisioned WalkHub.net as a place where people collaborate on documentation, like they do on open source code.

That is why we place great value on an active community.

We’ve learned, that if you want to build a community that will be involved in the development of your product and documentation, you have to provide a tool that makes it easy to create, reuse and share documentation between sites and projects.

Walkthroughs are especially suited for making reusable chunks of content. They define a new format of tutorials that are strictly structured and that can easily be adapted to the visual context of a website. As a result it is much easier to reuse Walkthroughs between projects. WalkHub.net is also designed so that it could become the home of a range of community collections and their Walkthrough tutorials.

We gathered the community by organizing documentation sprints, hangouts and personal success sessions. We have our IRC channel, where community members can reach out to us, while we reach out to them in our newsletter. Our community manager, Kata keeps all the threads together.

The challenge: different use cases, frequent updates

When documenting WalkHub we had to think of many use cases and scenarios, and build our documentation so that everyone can find the information they are looking for. We wanted to show how to create, edit, play and share Walkthroughs, how to install your own WalkHub and how to write copy that fits this new media format best. These topics are aimed at different people — Walkthrough creators, developers, technical writers — with very different skill sets, so we had to build our documentation so that everyone can benefit from it.
WalkHub on the other hand was and is very much a work in progress, so changes to the documentation happen frequently. We had to be prepared to choose a format that works well in an ever changing environment.

Why WalkHub?*

(*apart from practicing what we preach, that is)

WalkHub’s admin interface is quite complex, but you don’t have to know everything right away to start creating Walkthroughs. We broke down the workflow into tasks, and created a Walkthrough for each task. This way you can immediately start accomplishing your goals with WalkHub without the need to read even one line of the user manual.

Each Walkthrough has a widget automatically created from the Walkthroughs steps. We used widgets to create WalkHub’s documentation page with visuals. You can use WalkHub’s documentation as you see fit:

  • look for topics in the manual
  • skim through the steps of a task in the widget
  • play a Walkthrough and start doing your task right away

We also use the widgets for tweeting about new features and showing the capabilities of WalkHub in blog posts.

WalkHub enables us to accept contributions to our user guide from all our users. Document a task with Walkthroughs and let us add it to our documentation page!

The solution: something old, something new, something borrowed…

We compiled our user guide by creating a unique mixture of:

  • Something old:
    A task-oriented user guide where you can quickly find help for the task you want to accomplish or just scroll through the topics to see what you can do with WalkHub.

  • Something new:
    Walkthroughs for each task that guide you through and help you accomplish the task at the same time. Walkthrough widgets are embedded in the user guide for each task that can be solved with a Walkthrough. You immediately see if a Walkthrough is available and can quickly skim through the screenshots of steps right on the documentation page. You can also share the Walkthrough from the widget if you found it useful.

  • Something borrowed:
    To keep up with frequent changes, all of our documentation was written in markdown and is shared and synced through GitHub. It’s also open source, so feel free to use it for your own WalkHub!

You might want to go one step further than creating Walkthroughs and set up your own WalkHub: We created a separate guide for developers with detailed information on how you can install your own WalkHub or add the WalkHub JavaScript to your website.

As the Walkthrough format is still new, we added a style guide with some quick tips from technical writers and experienced Walkthrough creators. Be sure to check it out when writing copy for your Walkthroughs!

Diána is a Senior Technical Writer at Pronovix. She is specialized in API documentation, topic-based authoring, and contextual help solutions. She writes, edits and reviews software documentation, website copy, user documents, and publications. She also enjoys working as a Program Monitor for NHK World TV and Arirang TV. She graduated as a programmer, then went on earning system administrator and system analyst and designer degrees. She's fluent in English and German, and worked as a translator for a publishing company translating books from German to Hungarian. She's the Hungarian translator of Basecamp. Before becoming a writer, she worked with international clients like Sony Pictures Television, Da Vinci Learning and The Walt Disney Company as a key account manager in integrated marketing campaigns focusing on digital media.

Newsletter

Articles on devportals, DX and API docs, event recaps, webinars, and more. Sign up to be up to date with the latest trends and best practices.

 

Subscribe