News | About | Get Frugalware | Packages | Documentation | Discussion Forums | Bug Tracker | Wiki | Community | Development

Sample Template

From FrugalWiki

Jump to: navigation, search
Tango-document-new.png This article is a stub.
This typically means the article is a placeholder for more content to come. Knowledgeable users are encouraged to help expand the article.

NOTE: This is a generic template. This is also just a proposal for how templates should look like. This template is not meant to be used at all.

Before using this template, please read the Page Templates Guide. After that, please read the instructions in this template carefully.
This is where an overview text should go. An overview gives answers to following questions:
  1. What do I want to achieve with this article?
  2. How do I achieve the goal?
For example, if I talk about installing drivers for my XYZ modem, the answer to the first question is: "This article will help you install drivers for your XYZ modem". The answer to the second questions would be: "This article will show you how to download, unpack, and compile/install/configure the driver."
Of course, you don't need write the answers the way I did. You just need sensible answers to the two questions.

Contents

Article header

This is the article header. In some templates there is no article header. The purpose of an article header is to prepare the reader for the rest of the article (the main part). You mention following things here:

  • What texts should one be familiar with before he/she can read on?
  • What programs/hardware/tools should one have in order to be able to understand this article and/or carry out steps proposed by the author?
  • What additional steps should one take before reading the tutorial?

Note that you may not resort to writing something like: "This article is for experts only, noobs beat it!" An experience level needed by an article should be described in terms of texts read, ability to carry out concrete administrative or other tasks, etc.

Programs/hardware/tools should be listed if/when applicable. For example, in the example guide to installing XYZ modem, I would place a photo of the modem (if I can find/shoot one). Also, I would list the types of modems that are compatible with this procedure, and so on. Moreover, I would list dependencies required by the driver if those are not automatically resolved by pacman (for example, for manual compilation, etc).

Additional steps would usually be other wiki pages describing steps readers have to carry out in order for their system to be in a state that enables using the article. For example, an XYZ modem installation requires you to have XZZ system component configured in a certain way, as described in XZZ configuration page.

This is also a good place for discussing possible legal implications of following steps in the article, etc.

(NEXT: Article body consists of one or more headings leading readers through the topic. Typical article body consists of an introduction that prepares the reader, sets the mood, etc. Next comes the core of topic discussion, and some extra info at the end of the article.)

Introduction

Introduction (the title of this heading may be different for different templates) is a part of the article that prepares the reader for the very core of the topic. It sets the mood (e.g, tell you how difficult or easy the following steps may be) warns readers of caveats, etc.

Main discussion

Main discussion outlines the steps required to achieve a goal, presents information, and conveys an idea or a phylosophy.

Headings

For better organization of the article, the main discussion should be divided into headings. Headings should be used to group steps into logical units.

If you have only one step in a heading, you probably don't need a heading. However, if you identify groups of steps or ideas, you may put them together under a heading.

Headings may also be used to mark important sections of the article (since headings appear in the table of contents, they would make it easier for readers to find sections of particular interest to them).

Note that headings are not means of text formatting. You must follow the logic underlaying the heading system. Subheadings always go under next higher level heading.

For example: Heading level 2 is under Heading level 1. Heading level 3 is under level 2. Heading level 3 is never directly under level 1.

Cueing

To make parts of the text stand out, you will have to use various cueing techniques. Common techniques include:

  • Italics
  • Bold
  • Code box
  • Lists

Before discussing cueing techniques, you should keep in mind that using too much cueing may render cues ineffective. Cues should be used sparingly to be trully effective.

Italics

Italics are commonly used to mark a citation, titles, messages that are displayed on screen, and so on.

On FrugalWiki, italics should be used to present:

  • Something that someone said.
  • A quotation from an article (possibly followed by a link)
  • Screen output
  • Keyboard input

Example of italics: This text is in italics

Bold

Bold text is used to give strong emphasis to parts of text.

On FrugalWiki, bold text should be used to present:

  • Important warnings and notes
  • Must-follow instructions
  • Notes to readers such as "This part of the article is incomplete".

Do not apply bold to entire paragraphs.

Example of bold text: Some bold text

An example of a note:

NOTE: This article is still under development.

Code box

Code boxes are typically used to present parts of source code, screen output, input.

On FrugalWiki, code box should be used to:

  • present parts of configuration files
  • present screen output that has multiple lines (for one-liners use italics and write the text inside the paragraph)
  • present input required from the user

Here are some examples:

Error code 103
Hit any key to continue...

(If you want a single line screen output, you may do it like this: Error code 103 Of course, if you still want the screen output to stand out, you may use the code box for added emphasis).


In order to execute pacman system update you need to type in:

pacman -Syu

(Same applies to keyboard input example as the example above. If you have a single line command, you may use italics and write it inside a paragraph like this: pacman -Syu unless, of course, you think added emphasis is in order.)

NOTE: To avoid confusion, it is usually advisable to separate screen output from the commands that caused them.

For example:

Type in:

modprobe fglrx

If you get a following error:

error inserting module fglrx.ko

Then you're screwed.

This is not always necessary, but if you have a command that splits many lines of output, you need to either selectively present important lines or separate output from input. In general, it is better to split keyboard input and screen output.

Lists

There are two types of lists. Unordered lists (bulleted lists) that have no apparent order of items, and ordered lists which introduce numbering and thus order the list items.

You should generally use unordered lists as long as the order in which items appear is not the primary concern.

For example:

Pacman is used for:

  1. installing packages
  2. removing packages
  3. updating the local package database
  4. keeping the system up-to-date

The list above is wrong. It should have been a bulleted list, like this:

Pacman is used for:

  • installing packages
  • removing packages
  • updating the local package database
  • keeping the system up-to-date

Next example is an ordered list:

To update your system:

  1. remove packages you don't need so they won't get downloaded and updated
  2. update the system by issuing pacman -Syu command
  3. (in some cases) reboot your system for some changes to take place

Ordered lists are sometimes also used when you have a whole bunch of items and you need to show exactly how many items are present in the list:

There are four methods to do XYZ:

  1. Method A
  2. Method B
  3. Method C
  4. Method D

Style

Although there is no particular writing style requirement on FrugalWiki, you still need to keep in mind the following:

  • All articles are read by all users, so you need to understand that some things you say may not always be clear to everybody. Sometimes you need to explain some well known facts in plain (insert your language here). If necessary, point readers to resources that may clear up your statements.
  • You have to keep in mind that you are talking to a wide audience. Talk to readers (you, the readers).
  • This part of this article has to be expanded by the community to form the basis of a complete style guide.


Conclusion

Conclusion (title may vary depending on the template) is the part of an article that gives directions for further investigation, reading, testing, etc. It may also give some auxiliary info not strictly on-topic. In my example of XYZ modem installation, this part of the article may contain some general info on XYZ modems, like manufacturer website, XYZ modem users forum, a thread in the Frugalware forums discussing the device, XYZ modem technical data, etc.

Personal tools
Namespaces
Variants
Actions