WikiGardening

This page aims to guide the creation and style for new Wiki pages in the Kernel/ Documentation section of the page. The currently outstanding gardening tasks can be found on the Kernel/WikiToDo.

Consistency

We should be aiming for a consistent look and feel. At a minimum all pages in the kernel documentation should include the standard Kernel/MenuBar:

  • <<Include(Kernel/MenuBar)>>

Those which are longer should have a menu and a floating table of contents:

  • <<Include(Kernel/MenuBar)>>
    ||<tablestyle="float:right; font-size: 0.9em; width:40%; background:#F1F1ED; margin: 0 0 1em 1em;" style="padding:0.5em;"><<TableOfContents>>||

Namespace Layout

Pretty much all pages should be placed under the Kernel toplevel directory, within this we should try and place the pages under the broad topics shown in the table below. Pages which are clearly in a section should be included within that section, that is they should reside as a subpage of that page, for example Kernel/Debugging/FixingSomething. Within each section any repeated instructions (see below) should be included in a section specific Action subdirectory. All Topic sections should be added to the Kernel/TopicList so that they appear on the Kernel topics table.

Repeated Instructions

It will often be appropriate to try and include clear instructions on an activity (for example checkout an Ubuntu repository) in more than one place in the documentation. It is imperative that all of these cases have the same instructions and that they are easily maintainable. To allow them to remain within the original flow of the text, these should be pulled out to separate page fragments which can then be included directly. Each should include the title as a second level (==) header:

  • == Obtaining the source for an Ubuntu release ==
    
    The master source for each Ubuntu release is maintained
    in a git repository on the kernel.ubuntu.com, at the
    URL below:
    [...]

These can then be included as required using the incantation below:

  • <<Include(Kernel/Action/ObtainSource)>>

Where the title is not appropriate for the flow of your document you could use the following:

  • <<Include(Kernel/Action/ObtainSource, , from="== .* ==$")>>

Moving pages

When a page moves from one place to another it is imperative the old name continue to work. Any number of immutable Launchpad comments may point to the old name of these pages and we need those to end up pointing to the appropriate replacement page. When moving a page you may replace the original page with a link to the new page as below, add this to the very top of the wiki raw text:

  • #redirect Kernel/Name

Kernel/WikiGardening (last edited 2010-07-01 18:59:43 by apw)