Revision as of 16:54, 7 February 2008

Template:Documentation/Banner Template:Documentation/DraftPage Template:Documentation/BeingEdited

This article helps you to contribute effectively to the Documentation part of the wiki.

Structure of the Documentation Section of the Wiki

The Documentation section is only part of the large OpenOffice.org Wiki. The doc.oo.o project tries to present the information in this section in a way that it is easily accessible and has a structure that allows straightforward navigation for both users and contributors.

All documentation pages are subpages of the main Documentation page. A further substructure presents sections as subpages containing further subpages. Think of it as a hierarchical representation, just like a file system.

The current wiki page tree looks like this:

wiki.services.openoffice.org/wiki/Documentation
   |
   +---Dashboard
   +---Administration Guide
   +---FAQ
   +---How Tos
   +---OOoAuthors User Manual
   +---Tutorials
   +---Samples, Templates and Clipart
   +---Setup Guide
   +---BASIC Guide

Using Categories

Look here if you are unfamiliar with Wiki Categories.

A simple example of how to use Categories in Wiki books:

1. Create a Category named after the current chapter.
2. Add all pages of that chapter to the chapter Category.
3. Add the chapter Category to the book Category.

The reader can then view the book Category. The book Category shows all the chapters in the book. If the reader clicks on a chapter Category, they can see all of the pages in that chapter (in alphabetical order).

Do not add a category and its subcategory to the same wiki page. For more information see the MediaWiki Help:Category section on Category considerations.

You can use Templates to add a common category to a large group of pages, but it is not recommended. It may appear to save time, but "adding or deleting a category tag in the template does not add or delete the listings on the category page of pages that use the template, until some edit is made in the page that uses the template." For more information, see the MediaWiki Help:Category section on Using templates to populate categories.

Templates

Look here if you are unfamiliar with mediawiki templates.

Adding a new documentation template

• If you create a new template to be used in the wiki documentation, name it as a subpage of Documentation
  • wrong: mytemplate
  • right: Documentation/mytemplate

• Add a description of the template purpose and usage to the template itself using the element as described here

• Add the template to the list of templates below

List of Existing Documentation Templates

This is a list of Documentation templates and their usage

Template Name	Usage	Example
Template:Documentation/Abstract	Takes a short abstract of the chapter content of guides. Add to the top of guides. {{Documentation/Abstract|Abstract Text}}	See, for example, this Administration Guide Chapter
Template:Documentation/Banner	Puts the Documentation Project "Banner" at the top right of the page {{Documentation/Banner}}
Template:Documentation/BeingEdited	Marks a page as currently being edited to avoid conflicting changes. Use this template when you perform larger edits on a file that may even take more than one session to finish. Be sure to add name and date of "locking" by adding a ~~~~ as parameter: {{Documentation/BeingEdited|~~~~}}	Template:Documentation/BeingEdited
Template:Documentation/Caution	Takes sections containing warnings, i.e. information that is potentially harmful in some way, for example, data loss. {{Documentation/Caution}}	Never ever do what's written here.
Template:Documentation/CheckedAccuracy		This page is a candidate for speedy deletion. If you disagree with its speedy deletion, please explain why on its talk page and add a note to this page. If this page obviously does not meet the criteria for speedy deletion, or you intend to fix it, please remove this notice, but do not remove this notice from articles that you have created yourself. Justification: justification is not presented (justifications are not mandatory, but helps the administrator to evaluate). Administrators - Remember to check if anything links here and the page history before deleting.
Template:Documentation/DraftPage		Template:Documentation/DraftPage
Template:Documentation/hbar		Template:Documentation/hbar
Template:Documentation/HelpNeeded		Template:Documentation/HelpNeeded
Template:Documentation/Hook
Template:Documentation/Imported
Template:Documentation/LastEdited		Only works after update of mw engine to > 1.8
Template:Documentation/Linux		Template:Documentation/Linux
Template:Documentation/MasterTOC
Template:Documentation/NeedsRework		Template:Documentation/NeedsRework
Template:Documentation/Note		Template:Documentation/Note
Template:Documentation/OOo		Template:Documentation/OOo
Template:Documentation/Outdated		This page is a candidate for speedy deletion. If you disagree with its speedy deletion, please explain why on its talk page and add a note to this page. If this page obviously does not meet the criteria for speedy deletion, or you intend to fix it, please remove this notice, but do not remove this notice from articles that you have created yourself. Justification: justification is not presented (justifications are not mandatory, but helps the administrator to evaluate). Administrators - Remember to check if anything links here and the page history before deleting.
Template:Documentation/PDF		Template:Documentation/PDF
Template:Documentation/PRODUCTNAME		Template:Documentation/PRODUCTNAME
Template:Documentation/Tip		Template:Documentation/Tip
Template:Documentation/*TOC
Template:Documentation/Windows		Template:Documentation/Windows

Graphical Content

General guidelines for images are:

1. Use the image description page to describe an image and copyright status (if any).
2. Use a descriptive and unique title.
3. If possible, do not pre-scale the images you are uploading. Use the MediaWiki image thumbnail feature to scale the image.
4. Edit the image if necessary to make sure that the important part is clear and visible.
5. Keep in mind that people may be translating the page where you are placing an image. Try not to include callouts or other extra text on the image.
6. JPG is usually best for photos, SVG, for icons, logos etc, and PNG for screen captures. Try not to use BMP.

You can use the MediaWiki Image thumb feature to "wrap" your illustrations in an image box. This image box includes a spot for an image caption. The syntax is [[Image:image.png|thumb|position|size|Image caption]], where:

• thumb = thumbnail the image and wrap in an image box
• position = position on page. "none" places the image on the left of the frame with no text wrapping. "left" and "right" places the image on the left or right of the page with full text wrapping.
• size = max width in pixels for the image. If the image is larger than this value it is scaled down. If the image is smaller it is left as is.

If you do not declare a position and size, the image is scaled to a small thumbnail, and defaults to the right hand side of the page with full text wrapping.

An example using [[Image:LoadSaveOptions.png|thumb|none|500px|An example image caption]]

An example image caption

• Images cannot be hierarchical, filename should be constructed in a way so it shows the usage, e.g. Doc_mig_icon_data.png = Documentation image, used in the migration guide, depicting the database icon.
• How to handle image and table numbering?

Linking

General Editing Work

Fixing inappropriate, inaccurate, or outdated content

Fixing minor errors and typos

Fixing graphics and screenshots

Fixing Style and Language

Linking to localized pages

Validating Content

Fixing Spam

Working on FAQs

Working on Howtos

Working on Guides