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

This Raspberry Pi add-on lets you control Lego robots

Raspberry Pi is releasing an add-on that will let you use many of its tiny, inexpensive computers to control certain Lego robot motors and sensors. The add-on is called the Build HAT (HAT stands for Hardware Attached on Top), and slotting it onto a Raspberry Pi’s GPIO pins will give you four ports that you can use to control Lego Education’s SPIKE components, which the HAT and its software are specially designed for. It’ll also connect to most other parts that use an LPF2 connector, including the components from the Lego Mindstorms robot inventor kit. There’s also a Python library (basically a set of commands you can use to control the robot) available to go alongside the HAT, which will let you write software to control the robot parts you’ve got hooked up. Programing Lego’s SPIKE components with Python isn’t a unique selling feature from Raspberry Pi — the SPIKE kit comes with a hub that supports connecting six devices (compared to the Build HAT’s four) that can also store and run Python programs. Read more

today's howtos

  • How To Install Zikula on Ubuntu 20.04 LTS

    In this tutorial, we will show you how to install Zikula on Ubuntu 20.04 LTS. For those of you who didn’t know, Zikula is free open source software (FOSS) It allows webmasters and users to create great portals for secure extranet, online databases, e-commerce and multilingual sites. This article assumes you have at least basic knowledge of Linux, know how to use the shell, and most importantly, you host your site on your own VPS. The installation is quite simple and assumes you are running in the root account, if not you may need to add ‘sudo‘ to the commands to get root privileges. I will show you through the step-by-step installation of Zikula on Ubuntu 20.04 (Focal Fossa). You can follow the same instructions for Ubuntu 18.04, 16.04, and any other Debian-based distribution like Linux Mint.

  • How to Install Caddy Web Server on Debian 11

    Caddy is a free, open-source, and modern web server written in GO language. It is a lightweight and commercially supported web server that supports HTTP/2 and experimental HTTP/3 protocols. It can run anywhere with no external dependencies and is expanded via plugins. It is designed with security in mind and provides a number of features that are useful for hosting websites. In this tutorial, I will explain how to install the Caddy web server on Debian 11.

  • How to Install GIMP on Debian 11 Bullseye - LinuxCapable

    GIMP is free, open-source raster graphics editing software primarily used for image manipulation and image editing, transcoding between various image formats, free-form drawing, and many more specialized tasks. GIMP is released under GPL-3.0-or-later license and is available for Linux, macOS, and Microsoft Windows. In the following tutorial, you will learn to install the GIMP application on Debian 11 Bullseye using three alternative methods that you can choose from.

  • How to Install and Use PIP Python Package Manager on Debian 11

    Pip is a widely used package manager for the Python programming language. It is being used for installing and managing additional packages that are not available in the Python standard library. It allows users to search a package from the python packages index as well as install its dependencies. Pip is also known as a "Preferred Installer Program" that can create a completely isolated environment for the Python application. In this article, I will show you how to install and use Pip on Debian 11.

  • How to Install Visual Studio Code Cloud IDE on Rocky Linux 8 [Ed: It is proprietary, it is spying, and it needs to be shunned]
  • How to Remove Trash Can Icon From Left Dock Panel in Ubuntu 21.10 | UbuntuHandbook

    This simple tutorial shows how to remove the trash icon from the dock in Ubuntu 21.10 Impish Indri. Different to the previous releases, Ubuntu 21.10 puts the trash icon on left dock instead of the desktop. However, I don’t use the trash icon in either location. Instead, I removes files using right-click menu options, and go to trash via file manager left sidebar. If you also find it useless, then here’s how to remove it either via a single command or by a graphical configuration tool.

  • How to create a user and add it to the sudoers group in Rocky Linux

    In Linux administration, best practice recommends running commands as a regular user with sudo privileges. This user is simply known as a sudo user, and the user bears root privileges to perform elevated tasks in the system such as installing, updating, upgrading, and removing packages to mention a few. To execute privileged commands as a sudo user, the word ‘sudo’ precedes the actual command. Sudo is short for Super User do and when invoked, it allows underprivileged users to perform elevated tasks using root privileges. By default, the regular user created upon installation is simply an underprivileged user. Thankfully, you can add the user to the sudoers group to impart root privileges. This will allow the user to perform elevated tasks in the system just as a root user would. In this tutorial, we demonstrate how to create a user and add them to the sudoers group on Rocky Linux.

  • How to install Apache, MariaDB and PHP (LAMP) on Debian 11 – VITUX

    The LAMP stack is a collection of open-source software products that are frequently used in conjunction. The acronym LAMP is used to describe a computer system that has the following components: Linux, Apache HTTP Server (or just server), MySQL and PHP/Perl/Python. A user can install all of these components separately on a single computer or, more commonly, on separate computers connected by a network; however, some components are dependent upon other components – for instance, it is not possible to install Apache without first installing Linux – hence the standard installation practice is to install all components on a single computer system. The LAMP stack is the combination of open-source software to form a server environment most commonly used in web development.

  • How to install OpenSSH server on Alpine Linux (including Docker) - nixCraft

    This quick tutorial explains how to install and set up OpenSSH (SSHD) server and client on the Alpine Linux system. Further, you will learn how to build a Docker Linux container running sshd server based upon Alpine Linux image too.

  • How to use Shazam on the Linux desktop with SongRec

    Are you listening to a song and don’t know the name of it? Want to “Shazam” it but don’t have an Android or iOS phone? Check out SongRec! It’s an unofficial Shazam client for Linux. Here’s how to use it to “Shazam” on the Linux desktop.

  • Installing KDE On Linux Mint Cinnamon Base - gHacks Tech News

    If you’re like me and really enjoy using the KDE Plasma desktop environment, especially as it’s become very lightweight over the last year or two compared to the past where it was known as very heavy on resources, you are probably disappointed that Linux Mint does not offer a KDE version of its popular Ubuntu-based distribution. However, installing KDE is very easily accomplished, and doesn’t take very long.

  • A Fresh Installation of Debian 11 Bullseye

    August 14, 2021, marks a new major release for the popular Debian Linux distribution. Codenamed Bullseye and chock-full of enhancements as well as software updates after 2 years, 1 month, and 9 days of development, this release will be supported for the next 5 years. This guide will walk through a fresh installation of Debian 11 Bullseye’s new operating system. With this new release comes quite a bit of new functionality. One of the most welcomed changes is an updated kernel. Buster (Debian 10) was still running 4.19 but now with Bullseye (Debian 11), the jump to 5.10 has brought some wonderful hardware support!

Games: Trine 3 on Linux, Stellaris: Aquatics Species Pack, Cassette Beasts, Julius 1.7

  • How to play Trine 3 on Linux

    Trine 3 is an action/puzzle-platformer video game developed by Frozenbyte. It is the successor to Trine 2 and was released on August 20th, 2015. The game is on Microsoft Windows, Xbox, PS4, Mac OS, and Linux. Here’s how to get it working on your Linux PC. [...] Trine 3 works on Linux as a native game, but you’ll have to install the Steam application first if you want to play it. Thankfully, Steam works on a majority of Linux operating systems. Unfortunately, the software doesn’t come pre-installed on many distributions, so we’ll need to go over how to get it working first.

  • Stellaris: Aquatics Species Pack announced, launching with the free 3.2 update | GamingOnLinux

    Paradox only recently talked about a bunch of changes coming in the free 3.2 update and now they've announced Stellaris: Aquatics Species Pack as the latest DLC. "Sail the intergalactic seas and uncover an all new expansion packed to the gills with new options for new and longtime players alike. The Aquatics Species Pack will rinse Stellaris with a rising tide of new content, including brand new origins, species traits, civics and a treasure trove of new cosmetics. Seafarers and landlubbers alike will agree that this is Stellaris’ most immersive species pack to date.

  • Monster collecting game Cassette Beasts gets a new trailer and publisher | GamingOnLinux

    Cassette Beasts is the upcoming monster collecting game from Bytten Studio and today it has been announced that Raw Fury has joined as publisher. Bytten Studio had been looking for a publisher for some time now so this is great news. Developed in the open source Godot Engine, Cassette Beasts looks like a monster catching game like no other as you use the powerful fusion system to transform into creatures using retro cassette tapes.

  • Julius 1.7 is out, an open source re-implementation of the classic Caesar III | GamingOnLinux

    Julius is another shining example of an open source game engine re-implementation done well and a major update is out. Taking the original Caesar III and upgrading it for modern computing platforms. Not by the original developers though, this is like others, totally unofficial but don't let that stop you enjoying a much improved experience.

Karanbir Singh stepping down from the CentOS Board

Today we have heard from KB that he is stepping down from the CentOS Board of Directors. On behalf of the Board, I want to thank KB for his years of leadership. His work on the project, and in the community, has made the world a better place in tangible ways that affect millions of sysadmins on a daily basis, and that's hard to measure or quantify. On a personal note, I've appreciated his advice, insight, and mentorship as I took the reins of the Community Manager position. His stories and introductions paved the way for success in a role that has been very rewarding and a lot of fun. Read more Also: CentOS Project Chair Karanbir Singh Steps Down