Meta:Offline Documentation

From Daya Bay

Jump to: navigation, search
Offline Documentation: [Offline Category] [FAQ] [Howto] [Reference] [Manual]


Offline Documentation
This article is part
of the Offline Documentation
Other pages...

Offline Category
FAQ
How Tos
Reference
Manual
Getting Started
Software Installation

See also...

General Help on this Wiki


A past poll showed that developers like this wiki for documentation because it is quick and fast to add to. Users rightly complained that it was difficult to navigate or to find useful information. This topic gives ways to improve the overall organization of the offline documentation by providing conventions and rules that authors should follow. The conventions are simple boiler plate that must be added to each topic.

Documentation Types

Documentation pages come in several types with different methods of organization. Each type (except the first) has a hand maintained page that organizes the individual sub-pages.

Random Page

This is some wiki page that has not yet been incorporated in the offline documentation. It will lack the header, footer and right hand side bar. When you find such a page, consider bringing it into the offline documentation organization.

FAQ

A FAQ page answers some question and follows the FAQ conventions.

Howto

A How to page gives instructions on how to do something. See How to write a how to for more information.

Reference

A reference page collects some information about something that is common for people to want to refer to.

Manuals

A manual page provides more formal documentation about some aspect of the offline.

Offline Documentation Page Conventions

Each wiki topic documenting offline software should place a header and a footer template. Please only edit the templates if you are comfortable doing so.

Header

The header template is

{{doc:header}}

See Template:Doc:header for more details of use.

Footer

The footer template is for a top level organizational page (FAQ, Howto, Reference) should have a footer template like:

{{doc:footer}}

A page belonging to each one of the top-level category should include the category name as an argument (first level capitalized, ie "Faq").

{{doc:footer|Category}}

See Template:Doc:footer for more details of use.

Side bar

The side bar can be edited by editing {{doc:header}} template.

Writing Guidelines

Some guidelines to consider when writing documentation:

  • Be brief but complete
  • Stay on topic, make new topics when needed
  • Provide working examples
  • Check for existing documentation to improve instead of starting new pages
  • Add links to related topics
  • Make wiki links even if there is no corresponding page, they will show up in Special:WantedPages
Offline Software Documentation: [Offline Categories] [FAQ] [Offline Documentation Category]
Personal tools