WriteTheDocs 2017 – Taking the writing out of write the docs

Speaker: Chris Ward

Documentation appears in many formats (e.g. HTML) where we can do more than just text.

Images

… not screenshots

They capture attention, and may be worth a certain quantity of words.

Maps are great to give context, as you can see with representational maps (which changes the size or position of countries), or subway maps.

Images can also aid understanding … but it is very hard to get it right. And yes, you can draw, and no, you do not need to draw for this. "Write first, edit later" applies to images, too. Or, you know, get somebody to draw an image after you figured out how the image should look like.

Embrace the medium. Encance the text. Images can be interactive. The downside: they are hard to translate and maintain.

Moving images

Try making an introductory one! It is cool because you get non-verbal communication and a more personal relationship. But it is a lot of effort, and you lose searchability, and naturally accessability.

Thera re combinations of text and video which work with search and SEO, catering to all, see lynda.com.

An alternative are animated GIFs to demonstrate simple things. They are simple, quick, small, can be automated, but are hard to edit.

Playgrounds

Interfaces/places where you can experiment with your product right in the documentation. This is easiest done for APIs since there are lots of tools for that already. For other stuff there are tools like JSFiddle, Codepen, JSBin, Repl.it, Katacoda, Scrimba. Alternatively build inviting CLI tools that interactively build an example project.

This is possibly the best way to demonstrate something complex, and devs love it. But it's not always relevant, you need to consider security implications, and you will probably need developer input.

Augmented/Virtual Reality

Document hardware, ready for teamwork. Show where things are, and what they do. Could we, in the future, use AR glasses to augment visible websites to enhance products and documentation with local knowledge.

This is fairly accessible since it is a mixed medium which is context aware, but it is very time consuming, it is still early days, and a whole new tool- and skillset is required.

Docsbots

Something like chatbots, just for docs. GitHub has HuBot which is mostly aimed at devops, but it could also deliver documentation via its plugins. And while a slack/chat window might not be the best place to deliver documentation, it might be a great place for users to look for documentation. A bot could, for example, guide a user through an information in a conversational way.

This also carries over to voice bots! Converse with the bot and let them tell you how to install or use a tool.