Howto: Write a howto

Share your own howto's etc. Not for support questions!
Post Reply
Site admin
Site admin
Posts: 5095
Joined: 2006-01-04 04:26
Location: Oslo, Norway

Howto: Write a howto

#1 Post by Lavene »

When writing a howto there are a few points worth observing in order to make it usefull to as many people as possible.
  1. 1) Write a short introduction where you state the objective of your howto. If you quote other people or link to other resources, give credit where credit is due. Do not breach any copyrights. Your howto must be free as stated in the "GNU Free Documentations Licence" or similar.

    2) Remember that the skill level of your readers varies greatly. Try not to assume a certain level of proficiency, and if you do; state so in the introduction. For example "This howto assume that you know how to compile a kernel". If your HOWTO apply only to one branch of Debian make sure to say so in the introduction. For example: "This howto explains <whatever> for Debian Sarge."

    3) Explain how to do things. For example, try to write something like "Open, as root, the file /path/to/file in a text editor and <do whatever is to be done>" rather than just "Add <whatever> to file".

    4) If your howto require packages from 'contrib', 'non-free' or third party repositories clearly state so. A lot of people do not want non-free stuff on their system. When suggesting packages from third party repositories, verify that it works well with Debian.

    5) Think things through when suggesting system wide changes like changes to configuration files, sources etc. Ask your self if the changes will have undesirable effects on system upgrades, package upgrades, kernel change etc. If it can have such effects, clearly say so.

    6) Remember that your howto is intended for Debian users so try to stick with the Debian ways to do things. If you deviate from that, explain why.

    7) Verify your method of doing things. In Linux there may be several ways that seem to work but will later break. You should seek to stay within common conventions to ensure compatibility with future upgrades even if you personally disagrees with the conventions it self. If you are unsure, seek advice before subitting your howto.

    8) Monitor your howto for replies (use the board's topic subscription option). If someone posts a correction, verify it and if correct, edit your original post with a note about what you have changed and why. There is no shame in correcting your howto, this is how a community works.

Post Reply