--- title: Questioning the doc description: 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 […] url: https://canonical.com/blog/questioning-the-doc?format=md --- 1. [Blog](https://canonical.com/blog) 2. Article --- [Bill Wear](https://canonical.com/blog/author/billwear "More about Bill Wear") 9 April 2020 # Questioning the doc [sc:snap:maas](https://canonical.com/blog/tag/scsnapmaas) --- Share the article Here’s a [VLOG](https://discourse.maas.io/t/maas-show-and-tell-2/1411) 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](https://discourse.maas.io/t/maas-show-and-tell-2/1411) explaining the new look and the process by which we got there. [Get in touch Interested in running Ubuntu in your organization?](https://ubuntu.com/about/contact-us/form) ## Sign up for our newsletter Get the latest Canonical news and updates in your inbox. Work email: \*I agree to receive information about Canonical's products and services. By submitting this form, I confirm that I have read and agree to [Canonical's Privacy Policy](https://canonical.com/legal/dataprivacy). Sign up ## Share on --- ## Related posts [### Bare metal Kubernetes as a Service: Canonical MAAS and SpectroCloud Webinar](https://canonical.com/blog/bare-metal-kubernetes-as-a-service-canonical-maas-and-spectrocloud-webinar) Developers want Kubernetes infrastructure that is fast, consistent, and without limits! Platform engineering, IT, and DevOps teams are adopting Kubernetes as a Service (KaaS)... [Anton Smith](https://canonical.com/blog/author/anton5mith) 1 February 2022 [### Understanding bare metal Kubernetes](https://canonical.com/blog/understanding-bare-metal-kubernetes) Bare metal Kubernetes is a powerful set of technologies that builds on the best ideas behind the public and private cloud, yet abstracts away some toilsome aspects related to... [Anton Smith](https://canonical.com/blog/author/anton5mith) 27 January 2022 [### Bare metal Kubernetes: The 6 things you wish you knew before 2022](https://canonical.com/blog/6-things-you-wish-you-knew-about-bare-metal-kubernetes-before-2022) 2022 is right around the corner, and it’s not just time to prepare for Christmas, play video games, buy presents, or share anti-Christmas memes. It’s time to start making some... [Anton Smith](https://canonical.com/blog/author/anton5mith) 14 December 2021 [### Linux deployment tools: MAAS 3.1 for hot metal](https://canonical.com/blog/linux-deployment-tool-for-hot-metal) Back a few months ago, we did a feature poll on our MAAS forum, and the most-requested new feature turned out to be “Recommission/rescan a machine after it has been deployed“.... [Bill Wear](https://canonical.com/blog/author/billwear) 13 December 2021