wiki.ipfire.org

The community-maintained documentation platform of IPFire

User Tools

Site Tools


wiki:quickstart

Quickstart

Beware that this page is not finalized. This article is a work in progress. This note will be removed as soon as the article's finished

Reviews and comments explicitly wanted! Leave me a message at the forum (username is luxifer). There's also a discussion there.

This article is the guideline one should consider when editing this wiki. It will not go into detail on the basic usage of a wiki - only on the rules of content creation at the IPFire wiki.

Reference?

There are users who like to create or edit articles in this wiki. Often one doesn't know for sure how such an article should appear. The purpose of this article is to be a self-explanatory reference for your own article to create or edit. Basically, here you shall get the idea what to consider when it comes to the formal structure of your article. So, this paragraph is an introductional explanation on what this article is about - something that should precede every article. (1)

Yeah, but...

How does it work? Where do I find things? I don't know how to do that! Someone surely will be confronted with these questions. This article isn't meant to give a complete set of instructions. However, this article links to other articles at this wiki which contain all information required for article creation and editing and explains why those rules make sense. Without reading those other articles (referenced in the “Things to know” box preceding this article), understanding this article completely is not possible. A good article should always point out its limits and describe not just the information contained in that article, but also what information the article doesn't contain.

Structure

There are some important functions this wiki provides for formatting text consistently and appealingly. A good article sticks to the following guidelines:

Preceeding the actual text

Assumed knowledge

To explain specific facts or solutions to a problem it's often necessary to resort to further knowledge of other things. However it doesn't make sense to repeat instructions which already exist in another article, since the same information would have to be maintained in multiple locations.

You shall indicate which knowledge you assume the reader of your article to have in a “Things to know” box preceding your actual article. This way you only have to create links to the appropriate articles, your article will stick to its essential information and retain its clarity. Additionally you can reference to the prior enlisted articles on “Things to know” by linking to them in your text labeled by its number like this (2). In this article you will also find such references.

Inside the actual text

Besides the guidelines concerning content (1) inside the actual text, there are other things to consider when making your text more accessible and easier to understand. Therefore the following formatting shall be used:

Syntax Result Usage
**bold text** bold text parts of a sentence that need emphasis for their importance over the rest of that sentence or to clarify that they shouldn't be interpreted but to be considered exactly as written
//italic text// italic text paths through menus like System → Dial-up
''monotype text'' monotype text to format input and code

Boxes

To make certain text really stand out there are several different kinds of text boxes. Please use boxes only for their appropriate use to keep your article accessible.

A simple box is a code container.

# A common usage would be quoting of a files content.
# This may be a configuration file, for example.
foo  =  bar

# Note that whitespaces are preserved!

Another common type of box is the note box. These are more graphically intense, and are for things intended to stand out for their importance.

For example, it would be nice if you're warning the reader that there's a point in your article where following the instructions may carry risk of breaking something.

Pictures

Screenshot
Sample Screenshot

Sometimes it's a good idea to add pictures to your article (eg. screenshots), because sometimes a picture can really help the reader understand an explanation. Please consider the size of pictures you put into your article and allow the Wiki to resize them if they're too big, especially when handling screenshots. Also please use PNG or JPG as the filetype for pictures.

After the actual text

Much like a good book or movie, a good article ends with references to further information or a forecast of upcoming articles.

Tips

  • If you don't feel entirely fit for editing this wiki right now it's no problem. No one will complain so don't let it hold you back. You may just get started and let your confidence rise as your experience does. After all this is a community and others will help you get started, too. Just check out the forums.
  • When editing an article it's locked for editing (by a user other than you) to reduce the risk conflicts by having multiple people editing (and eventually saving their version) of the same article at the same time. However this lock expires after a certain amount of time. You will be notified before that happens if you still have the edit page opened. Be aware that hitting the Preview button in the editor refreshes the lock.
  • If you don't know exactly how to type certain mark-up so it looks the way you want, just edit another article which has the desired figure in it and copy the mark-up from its source. When doing so, please leave the editor of the other article by clicking on Cancel, so as to not save any accidental changes or leave the article locked for editing.

If you don't have a lot of links you don't have to categorize them.

Internal

External

wiki/quickstart.txt · Last modified: 2018/09/14 14:42 by Peter Müller