home

Conventions for wiki structure and content

Guide for editing pages on the Arch Women wiki.

Breaking the conventions described here is fine if it makes sense to. These are not hard rules.

Useful links:

Wiki structure

This section is unfinished. Please help us complete it.

This is a list with descriptions of the namespaces and some important pages in this wiki.

  • wiki
    • :start
      to-do list, links to subpages
    • :conventions
      this page!
    • :team
      wiki team
    • :dokuwiki, :syntax, :welcome
      read-only pages tracked by upstream's git
  • aw-tech
    server administration
  • aw-org
    AW organization
  • meetings
  • projects
  • todo
  • user
  • tag

FIXME fill in description
FIXME make names into links

Formatting

Pages and sections

In a page's URL, use an underscore '_' in place of spaces and not a hyphen-minus '-'. Many parts of DokuWiki assume an underscore stands for a space, such as namespace_templates and plugin:pagelist.

The first headline is the page title. It should be level 1 (six '=' characters). All other headlines in the page are of higher levels and designate the sections of the page.

For capitalization of page titles and section headlines, use sentence case. “Title for new page” is fine, while “Title for New Page” is not. This rule does not apply to agendas of old meetings (before the 54th meeting), pages in :wiki from upstream (DokuWiki, Syntax, Welcome), and any page in the namespaces :todo, :user, :playground, :tag.

A page should begin with a (brief) description of the topic the page covers. It is followed by a list of links and information for quick reference.

The primary page of a namespace is the :start page and has information about the namespace, such as a description and an index of the pages in the namespace. The title of the namespace is taken from the title of its :start page.

Unfinished pages and sections

If a page is unfinished, tag it as a stub. Do not make any banner or announcement that the page incomplete.

If a section is unfinished, paste the following at the top of the section: {{section>wiki:include:unfinished#section&nofooter&noheader}}

To create a new unfinished page, make the page with a skeleton of the sections you think it will have. Then mark each section as unfinished. Also tag the page a stub.

Use the FIXME emoticon to draw attention to specific lines.

You can find a list of all stubs here and a list of pages with unfinished sections here.

Including other pages

Use the include plugin. You can also include sections of another page instead of the entire page.

Examples:

Description Example
including an entire page {{page>target_page&nofooter}}
including a section without the section title {{section>target_page#target_section&nofooter&noheader}}
including a section with the section title {{section>target_page#target_section&nofooter}}

Examples in the wiki:

Example Target Description
Include: Unifinished Unfinished: Usage The entire section is included from the usage section of the target.
Classroom: Upcoming Classes Upcoming Classes The entire page is included in a section. This particular example uses many options provided by the include plugin.
Meetings: 2015 February archive and bracket_old When a meeting is over, the same text is added to the meeting pages.

Notes and warnings

This section is unfinished. Please help us complete it.

Tags

Tags are listed at the bottom of a page.

Conventions of specific namespaces

aw-tech:

The aw-tech: namespace is for the technologies used by Arch Women. Pages in the aw-tech namespace document procedures and checklists as well as useful information and links to resources.

The goal is to have notes on,

  1. Usage - We work on Arch Women part time and do not have everything at the tips of our fingers.
  2. Setup and configuration - In an emergency, we must have the information necessary for quick restoration.

Common elements:

  • list of information, URLs, and filesystem paths
    see section on lists below
  • to-do table
    see the section on to-do below
  • usage
  • upgrade
  • initial setup (and installation)
    notes on how we installed it the first time
  • configuration
    description of how it is configured (public info. only)
  • backup
    procedures for backing up
  • testing
    see the section on testing below

Don't document obvious things. If the process of upgrading is to run pacman -Syu then don't include a section on upgrading.

The page should start with a brief description of the technology. (Consider why we're using it.) This is followed by the list of information. That is followed by the to-do table. The rest of the page is divided into subsections.

For many technologies one page is sufficient for all their notes. If the notes are too much for a single page, the technology can be assigned its own namespace under aw-tech. Place usage and commonly needed informkation in :start. Things are needed very rarely, like setup, should go in their own subpages. Things which are small enough can go in :start but otherwise go into their own subpages if long and complex.

List of information

A list which is a quick reference to information and links to useful resources. Some things to consider:

  • upstream website
  • upstream documentation
  • Arch Linux package
  • users and groups
  • file modes
  • filesystem paths (data, configuration, and so on)
  • URLs on archwomen.org
  • Arch Women git repos (GitHub links)
  • links to tutorials

A list of information can be put at the top of a page or at the top of a section.

To-do table

This section is unfinished. Please help us complete it.

Testing

This section is unfinished. Please help us complete it.

projects:

Each project gets its own namespace under the projects: namespace. A project namespace has at least two pages, :start and :admin. The :start page is the landing page for people not familiar with the project wanting to know what the project is and how to participate. It gives an overview of the project. The :admin page is the internal administrative page and is the nexus for volunteers of the project.

On the :start page describe the project, its history, how it helps further Arch Women's goals, how to participate, and other information of interest to outsiders and new volunteers.

The :admin page will have the to-do list/table for the project, a list of team members, notes on procedures and common periodic tasks, and other administrative notes. If the :admin page becomes too large, it can be split up as needed.


wiki/conventions.txt · Last modified: 2016/11/27 02:37 by fsckd