In the Drupal community we excel at sharing code, but we are terrible at sharing documentation. I’ve been trying to rally the Drupal community around a standard for reusable documentation for a few years now. But to get people to collaborate we needed to invent a new tool that makes it easy to create, reuse and share documentation between sites and the Drupal project at large. We have built that tool, it’s called WalkHub.
WalkHub lets you host a new type of tutorials designed specifically for the Internet. It allows you to create Walkthroughs for web applications that record interactions and NOT the visuals of a process. So when your site changes they adapt: got a new picture on your frontpage? Your form has an extra field? The design of your site changed? No problem, the Walkthrough automatically updates itself. And when there is a change in the HTML that breaks a Walkthrough, you can get a warning from your test infrastructure so that you know when you need to go in and fix something.
But that’s not all. What I’m really excited about is how this will help our community. 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 will be 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.
This is the first post in a series of 10 posts about the WalkHub distribution that I will be publishing in the next few weeks that explain how we are going to make collaborating on documentation the best practice and default behavior, just like it is for patches to our code.
WalkHub is an open source Drupal distribution. It is still in Beta, but already now you could use it to redefine the way you do documentation on your projects, no matter if you are in the specification, implementation, user acceptance or production phase.
In this series I will talk about the following topics:
- How we play walkthroughs on any website on the internet - without downloads
- Recorder now live - what is it, what it means for Drupal
- Testing your documentation - how does it work, what can you do with it, what does it mean for Drupal
- Automatic screenshots and the WalkHub widget - how does it work, what does it mean for Drupal
- Poor man’s BDD (behavior driven development) - what is it, how does it work
- How collections work - D7, D8 and Commerce Kickstart collections, what it means for the community
- Personalize Walkthroughs, what it means for Drupal, how could you use it
- Prerequisites - building complex test sequences
- Taking it beyond tours - topics and maps - introducing Gitmap
When asked everyone agrees that documentation is essential. Even with the best possible UX there is always someone who will not understand some part of your web application. We want to make it our job to help communities, companies and individuals make the best possible documentation. But to do that we need your help:
Want to stop maintaining your documentation in isolation? Help us build a documentation set that the community can maintain with you.
We are looking for people that like making documentation, people that would love to spend a week in Budapest, working on the Walkthroughs for their web application of choice (be it Drupal, a Drupal distribution, or any other web application). We are especially looking for people that would like to help document Drupal 8 core, Commerce Kickstart, Drupal Commons, Open Atrium, Open Publish and Open Public websites. If you, or someone you know, is really familiar with one of these products and can get a week free to work with us at the WalkHub sprint meeting, get in touch!
If you can’t make that kind of commitment, you can still support our project’s crowdfunding campaign or help us spread the news!
https://www.indiegogo.com/projects/walkhub-tutorials-designed-for-the-internet/x/2076202
