Generic Bugs in Documentation

Certain bugs are so routine and minor that they go unnoticed. Fixing them would be a good start to learn the process of making a contribution to the DocumentationProject. Here are few ways you can find yourself such bugs. Before you start, make sure you have the latest source code for the project you are interested in.

Yelp validation failures

Yelp tries its best to display pages while ignoring some errors. These ignored errors are visible when you validate the pages. Usually they indicate broken links, incorrect Mallard tags.

You would need to have yelp-tools package installed on your system.

  • Navigate into the local git checkout of the project
  • Navigate into the help (usually located at help/C)

  • Run yelp-check validate *.page

If you see errors, then file a bug against the project in the GNOME bug tracker.

Grammar issues

We follow British English grammar but with American spelling.

Outdated screenshots and instructions

GNOME is released every six months and when it does, the user interface for a project may have changed. This makes screenshots in Help outdated. We aim to keep our documentation have screenshots of the latest stable release. You can help with this:

  • Update your GNOME version to latest stable on your computer.
  • Check screenshots available in Help against the real application in latest stable GNOME.
  • Make sure to use GNOME's default theme and not a custom theme set by your distribution.
  • If outdated, follow this guide to taking a screenshot.

Check validity of instructions in Help

  • Check the correctness of Help by trying out the instructions on the latest stable GNOME. If the application has a user interface or parts different from that written in Help, then file a bug and fix it.

Incomplete documentation

Often there is simply not enough information to write Help completely and for then are marked as TODO: within the code (the code for user documentation in *.page files). You can run a Find in all Files in your text editor and look for TODO: or todo. You can also look for the <comment> tag to look for help that is partially written.

Once you find such a file, consult with the author of the page before taking up the task.

DocumentationProject/GenericBugs (last edited 2023-07-28 13:30:20 by AndreKlapper)