Language Selection

English French German Italian Portuguese Spanish

Shaun McCance: Discovery Docs Part 1: Discovering Why

Filed under
GNOME

This is Part 1 in a series about the Discovery Docs initiative, which I will present about in my upcoming GUADEC talk.

A long time ago, in the days of bonobos and fishes, GNOME documentation was written as long, monolithic manuals. We split these beasts into digestible pages as best we could (which is to say, poorly) and hoped for the best. Then we had an idea. What if we actually controlled the granularity at which information was presented? What if, instead of writing books, we wrote topics?

And so we did. We weren’t the first software project to make this shift, but we were early on the curve, and we did it radically. While many help systems still try to shoehorn topics into a linear structure, our help focuses on creating a navigable web of information.

The question of how big the topics are — how big the chunks on the web are — is entirely up to us. For the most part, we have chosen small topics with the least amount of information we could get away with. The reasoning is that users can find quick answers to questions, and if they want to learn more, we have extensive cross linking. Our topics have mostly followed the familiar trichotomy of tasks, concepts, and references. Our documentation is deliberately excruciatingly boring.

Read more

Discovery Docs Part 2: Templates and Taxonomies

  • Shaun McCance: Discovery Docs Part 2: Templates and Taxonomies

    This is Part 2 in a series about the Discovery Docs initiative, which I will present about in my upcoming GUADEC talk. In Part 1: Discovering Why, I gave a brief history of GNOME documentation, and explained our current unabashedly boring task-based approach. I proposed focusing instead on learning and discovery in an attempt to attract and retain enthusiastic users. In this post, I’ll explore what a learning-based topic might look like.

    GNOME documentation currently focuses on tasks, concepts, and references, with tasks doing the bulk of the work. This is a common approach across the entire documentation industry, but that doesn’t mean it’s the only approach. Notably, we don’t strictly enforce these taxonomies as some other documentation systems do. Rather, we provide some templates and guidelines, and we trust humans to make good judgment.

    To shift to a more engaging approach, I’m exploring a lengthier topic type that I’m hesitantly calling a “lesson”. A lesson incorporates a concept, possibly a task, possibly a quick reference, and further reading for specific use cases or advanced users. It should be readable in about five to seven minutes. Let’s break down an outline of a lesson.

haun McCance: Part 3: Voice and Style

  • Shaun McCance: Part 3: Voice and Style

    This is Part 3 in a series about the Discovery Docs initiative, which I will present about in my upcoming GUADEC talk. In Part 1: Discovering Why, I laid the groundwork for why I think we should focus our docs on discovery. In Part 2: Templates and Taxonomies, I talked about how to structure topics differently to emphasize learning. In this post, I’ll talk about how we should write to be engaging, but still clear.

    One of the main goals of Discovery Docs is to be more engaging and to create enthusiasm. It’s hard to create enthusiasm when you sound bored. Just as your speaking voice can either excite or bore people, so too can your writing voice affect how people feel while reading. Boring docs can leave people feeling bored about the software. And in a world of short-form media, boring docs probably won’t even be read.

    This post has been the hardest in the series for me to write. I’ve been in the documentation industry for two decades, and I’ve crafted a docs voice that is deliberately boring. It has been a long learning process for me to write for engagement and outreach.

Shaun McCance: Discovery Docs Part 4: Discovery

  • Shaun McCance: Discovery Docs Part 4: Discovery

    This is Part 4 in a series about the Discovery Docs initiative, which I will present about in my upcoming GUADEC talk. In Part 1: Discovering Why, I laid the groundwork for why I think we should focus our docs on discovery. In Part 2: Templates and Taxonomies, I talked about how to structure topics differently to emphasize learning. In Part 3: Voice and Style, I proposed using a more casual, direct writing style. In this post, I’ll look at increasing reader engagement.

    “Nobody reads the docs.” This is a common complaint, a cliché even. It has some truth to it, but it misses the bigger picture. For this post, the more important point is that people don’t often seek out the docs. So if we’re writing interesting material, as I’ve discussed throughout this blog series, how do we reach interested people?

    This post is all about how we encourage people to discover.

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.

More in Tux Machines

Software: Matrix, Ktube, and Monero P2Pool

  • Chat Bubbles on Element and Several Matrix Apps

    This simple comparison wants to help everyone adopt alternative messaging technology, Matrix, with suitable user interface to them. We call Matrix Apps to instant messengers like Element, Fluffy, Nheko, Schildi and Spectral as they are created based upon the said technology. We will start by setting up criteria first that includes chat bubbles, then going through these messengers one by one, and you will see their pictures here along with a little comments from me. I hope you can pick up the messenger with UI you love the most from here.

  • Ktube Media Downloader lets you download YouTube videos easily on Linux

    I always like to tell people about how I have been using Linux as my primary operating system for over ten years. I love Linux, I understand it, it’s free and above all, it fits my workflow in a way Microsoft’s Windows (with all its goodness) probably never will. That also means I love and am a command-line ninja but I also know one thing, a lot of people out there fear and hate the command line.

  • Monero P2Pool V1.0 Is Released

    The latest version of P2Pool, a decentralized Monero mining pool has released. This is the first official release, signaling an invitation for more users to try out the new software.

Better Support & Performance For OpenACC Kernels Is Coming To GCC

While the GNU Compiler Collection has supported OpenACC for a few years now as this parallel programming standard popular with GPUs/accelerators, the current implementation has been found to be inadequate for many real-world HPC workloads leveraging OpenACC. Fortunately, Siemens has been working to improve GCC's OpenACC kernels support. GCC's existing OpenACC kernels construct has been found to be "unable to cope with many language constructs found in real HPC codes which generally leads to very bad performance." Fortunately, improvements are on the way and could potentially be mainlined in time for next year's GCC 12 stable release. Read more

Security Leftovers

  • Database containing 106m Thailand travelers' details leaked • The Register

    A database containing personal information on 106 million international travelers to Thailand was exposed to the public internet this year, a Brit biz claimed this week. Bob Diachenko, head of cybersecurity research at product-comparison website Comparitech, said the Elasticsearch data store contained visitors' full names, passport numbers, arrival dates, visa types, residency status, and more. It was indexed by search engine Censys on August 20, and spotted by Diachenko two days later. There were no credentials in the database, which is said to have held records dating back a decade. “There are many people who would prefer their travel history and residency status not be publicized, so for them there are obvious privacy issues,” wrote Comparitech editor Paul Bischoff on the company’s blog.

  • Break out your emergency change process and patch this ransomware-friendly bug ASAP, says VMware

    VMware has disclosed a critical bug in its flagship vSphere and vCenter products and urged users to drop everything and patch it. The virtualization giant also offered a workaround.

  • Reproducible Builds (diffoscope): diffoscope 185 released

    The diffoscope maintainers are pleased to announce the release of diffoscope version 185. This version includes the following changes:

    [ Mattia Rizzolo ]
    * Fix the autopkgtest in order to fix testing migration: the androguard
      Python module is not in the python3-androguard Debian package
    * Ignore a warning in the tests from the h5py package that doesn't concern
      diffoscope.
    
    [ Chris Lamb ]
    * Bump Standards-Version to 4.6.0.
    

GNOME 41 Released. This is What's New.

GNOME team announced the release of GNOME 41 with some exceptional changes and updates. We wrap up the release in this post. Read more