Help:Editing

From Helpful

Conventions

Not many.

Minimize visual clutter. For example, paragraphs are cool, and avoid overkill wikilinking.

Sections are useful for for summaries, for very detailed notes, and for lists of resources, and to split up things that are dozens of paragraphs long.

When adding web links, try to mention the title of the linked content to make them recongizable and easier to fix when they 404.

Links to the pages you are augmenting is handy. For example, linking to software's project page, (interesting parts of) manuals, datasheets, and such is nice. The wikipedia page may be a lazy way as it usually links on well enough.

Wiki syntax, templates, and such

Useful syntax notes elsewhere

• http://meta.wikimedia.org/wiki/Help:Table

• http://en.wikipedia.org/wiki/Wikipedia:Extended_image_syntax

Special characters

Some characters are special to the wiki's syntax parser, such as = {, |, }. To avoid this, in general pages and for text inside template arguments, it is probably simplest to use nowiki to temporarily disable all wiki-specific parsing:

{{comment|<nowiki>a template is made like {{templatename|args}}</nowiki>}} 

You could also use numeric entities, such as:

• {
  for
  {
• |
  for
  |
• }
  for
  }
• =
  for
  =

Templates

There are some defined templates you can use if you wish, currently including:

In-text:

• {{verify}} puts a bracketed 'verify me', useful when you're not entirely sure of what you or someone else states. Looks like (verify)

• {{comment}} make parenthetical text subtler in-page, and consistently style in the wiki, and easy to change in style later. {{comment|this syntax}} currently gives
  this effect
  . Useful for things like e.g.
  (This is not guaranteed to be thread-safe on all systems.)
  .

• {{inlinecode}} can be used in paragraph text to get a style that imitates text blocks (constant-width font, background color). {{inlinecode|this syntax}} currently gives
  this effect

• {{stub}} - nice whenever you dump in a few links and sentences in preparation, so for pages that haven't received real attention from writers/editors.
• {{unfinished}} -
• {{feelfree}} is unfinished with a "I'm not sure of more than this" twist

Feel like polishing? Pages with some of those markers:

• Stub
• Unfinished pages
• Feelfree pages
• Verify-me

Code

Note that the almost-verbatim one-space-indented wiki blocks can be made verbatim, no-extra-indentation-necessary by putting a <nowiki> around the contents, like (click edit to see the markup):

def yay():
  for i in range(10):
    print "thing %d"%i

As long as GeSHi is installed, you can also get syntax higlighting for various things. Wrap the code in <code lang="python">, </code>, or whatever the language is:

def yay():
  for i in range(10):
    print "thing %d"%i

More notes to potential editors

Anyone can contribute. Really, feel free. (Just know it might get reformatted:)

There are no real policies you are bound to. If you want some guidelines, take a look at wikipedia's editing policies and rules, they're mostly useful and/or sane.

When you write new pages, add an introduction, but avoid parts that are probably unnecessary. For exameple, consider that someone who searches for something like SSH tunneling probably knows basics about computer networking, so you can give the lowdown on how the tunneling works and what the most likely setups are.

A lot of web(log) articles out there have the tendency to explain so much background they feel they need to quickly skim over a few commands that, yes, work, but don't give the reader any idea of how or why.

In this example, if you feel like elaborating on networking details, you'ld probably want to add that to some networking-related page and reference that instead, so that you can avoid duplicate information (that could also be in places where it is harder to find).

Also, try to be minimal. There are often many side notes you can make that are correct and complete, but don't contribute to general understanding. Consider moving such details to a 'detailed considerations' section, removing it, or even moving it to its own article.

Things to avoid

Nothing here should consist for a noticable part of copy-pasted summaries. Things that are clearly rehashed rather than really understood will probably be commented out or removed until someone gets to writing it up well. Overly formal definitions, dry references consisting mostly of options only the very technical type of person (who can find them anyway) would be interested in.

See also Contributing and editing.

Note that the content is FDL'd, which rougly means "don't add copyrighted text, and note that the content is freely copyable" (see also License comparison)