Questioning the doc

Here’s a VLOG about some changes we’re making to the MAAS documentation. It’s all about using questions at the top of articles to help direct attention.

This idea grew out of our frustration over long pages with lots of complex information. We tried a top table of contents, but that looks weird and requires a lot of policing to keep up-to-date.

A couple of highlights:

– Questions don’t necessarily point to sections in the current article. We wanted to collect pointers to relevant info, no matter where it might naturally reside in the docset. Think of it as a cheap way to achieve transclusion.

– Not all pages rate questions. Pages that provide linear instructions — or pages that are very short — won’t use questions, because they’re not appropriate.

– When questions are arranged in a “knowledge gradient” (still working on this), readers can use the questions to dive in at the right level, without feeling frustrated wading through tutorial information.

– Attempting questions also helps us force out pages that are overly long or poorly structured. If there are too many questions, or it’s hard to form questions to describe a page, those are useful red flags.

That said, have a look at this VLOG explaining the new look and the process by which we got there.

Ubuntu cloud

Ubuntu offers all the training, software infrastructure, tools, services and support you need for your public and private clouds.

Newsletter signup

Select topics you’re
interested in

In submitting this form, I confirm that I have read and agree to Canonical’s Privacy Notice and Privacy Policy.

Related posts

Next WSLConf date set, CFP now open through 15th August

WSLConf is the first and only community conference dedicated to Windows Subsystem for Linux (WSL). Canonical proudly sponsored the first WSLConf in March...

The State of Robotics – July 2020

We know a lot of you are on vacation so we’ll keep this month’s State of Robotics edition short and sweet. Try out the Hello World of ROS Looking for an easy...

Infographic: Ubuntu from 2004 to 20.04 LTS

Today, the first point release of Ubuntu 20.04 LTS went live! To celebrate, we wanted to share how Ubuntu has evolved since the first release in 2004 to where...