Howto write a Howto

In this Wiki we will concentrate on neat little HowTos to help get things done. Back in the day, OpenWrt addresst itself specifically to users already having experience with Linux. Users knowing how things work and what they wanted. But since a while ago OpenWrt clearly addresses newbie-users as well, have a look at the simplicity (and modularity) of UCI and LuCI. Numerous UCI configurations are rather well documented. When we write HowTos, let us try to address them newbies, too. And of course, OpenWrt and this wiki welcomes offspring. People wanting to learn and contribute. Let's support them, too.

So before you write your HowTo, you should realize whom you are addressing, and also why you write it.

Whom are you addressing?

1.

  • other experienced users (experienced doesn't mean they know it all)
  • bloody beginners (a beginner is not an idiot but a person lacking knowledge and experience with Linux)

2.

  • people only wanting to get stuff done
    • Write a simple sequence of activities in the expedient chronological order; use verbs (download, install, configure, execute/run, expect to see, etc.)
  • people wanting to get stuff done and at the same time gaining a better understanding on how Linux/OpenWrt works
    • use the correct terms, e.g.
      • a "3G dongle" is actually a MODEM for the cellular radio standards, like UMTS, which happends to be connected through USB.
      • a "bluetooth dongle" is an adapter or converter between Bluetooth and USB.
      • USB is not a "technology" but a Bus_(computing).
      • IEEE 802.3 (Ethernet) is not a "technology" but a family of standards for frame based data exchange. It comprises of a couple of specifications.
      • IEEE 802.11 (WLAN or Wireless Ethernet) is a set of standards for data exchange over em waves instead of wire. Additionally to different specifications there are national laws governing the allowed frequencies and signal strengths. Provide links to specs and laws.
      • best if you do not use the term "technology" at all
    • explain what happens.
    • name concrete location: after installing the package you should find the files … in the directory … so we do not have to look for them
    • provide links to manpages like http://linux.die.net/man/ since not everybody runs Linux while reading your howto
    • provide links, especially to homepages directing themselves at scholars
    • provide links to projects being aimed at writing Linux drivers http://wireless.kernel.org, http://alsa-project.org, etc.

Why are you doing that?

  • to contribute a HowTo for a reasonable task (:!: highly wanted :!:)
  • to contribute a HowTo for an unreasonable task (From one nerd to another ^_^)
  • to explain things
  • to impress nerdy girlfriend
  • to make the world a less ignorant place
  • to demonstrate how easy things can be done, once you installed a Linux Distribution like OpenWrt
  • to share your knowledge

Back to top

meta/howtohowto.txt · Last modified: 2012/05/14 00:26 (external edit)