Presented by:

872c5814d788dacafae4e1fcd6b5615c

Carla Schroder (cschroder@suse.com)

Lifelong nerd, Linux howto author since 1995, author of hundreds of tutorials and three books: Linux Cookbook, Linux Networking Cookbook, and the Book of Audacity. System administrator, network administrator, happy member of the amazing SUSE documentation team, currently working on bleeding-edge cloud technologies. Other careers include managing editor, farmer, auto mechanic, handymam, photographer, and others lost in the misty dawns of time.

No video of the event yet, sorry!

Everyone is a newbie at 99% of everything, so teaching is the most important and noble task of all. Creating and maintaining documentation is not easy, but it is necessary. Documentation is recording your accumulated experiences and creating your institutional memory. Documentation is building a library of knowledge, and adding to the total store of recorded human knowledge. Documentation is a primary tool for bringing new contributors up to speed efficiently. Good documentation = happy users. Teaching how to use your software reveals its flaws, and expands your own expertise.

Creating good documentation is not easy, but it is just as necessary as writing code. There are many options for creating good helpful documentation: wikis, blogs, videos, slideshows, wherever your imagination leads you. The important bit is doing something.

Some of the elements of good documentation are:

Concise and to the point
Task-oriented and procedural, with examples of both correct and incorrect results
Simple and direct: teach one thing at a time

After you have created your documentation people must be able to find it, and find what they want in it. And then someone has to maintain it.

This may all sound a little scary, like it's complicated and a lot of work. I will show you how to minimize the pain and maximize pleasant results with proven tips and tricks learned from years of experience, such as SEO tricks to help users find your documentation, efficient tools and workflow, and how to encourage contributors.

Date:
2018 November 10 - 13:30
Duration:
50 min
Room:
Room 3178
Conference:
Seattle GNU/Linux Conference 2018
Language:
Track:
Documentation
Difficulty:
No experience required

Happening at the same time:

  1. Everyday Use of GNU Guix
  2. Start Time:
    2018 November 10 13:30

    Room:
    Room 3183

  3. Qubes OS: A reasonably secure operating system
  4. Start Time:
    2018 November 10 13:30

    Room:
    Room 3180

  5. How to learn Arduino by playing with fire
  6. Start Time:
    2018 November 10 13:30

    Room:
    Room 3184

  7. A case study in incrementing a language's major version: PHP
  8. Start Time:
    2018 November 10 13:30

    Room:
    Room 3179