Documentation/Dashboard/Wiki Editing Policy

From Apache OpenOffice Wiki
Jump to: navigation, search

Template:Documentation/Banner Template:Documentation/DraftPage

This article helps you to contribute effectively to the Documentation part of the wiki. We strongly encourage you to announce new pages or major changes to the mailing list dev@documentation.openoffice.org.


Prerequisites for Editing

You must be registered and logged in before you can edit the Wiki. Registration is easily done.

  1. Click on Log in / create account in the upper right corner of the screen and enter the required bits.
    We recommend using the same username as on the OpenOffice.org website.
  2. Subsequently you have to validate your email address.

For further logins you use the same entry point, enter Username and Password, and click the Log in button.

Next step could be to tell the Community about yourself. There is definitely no harm and it is a good way of getting comfortable with the Wiki.

  1. In the toolbox on the left side click Special pages.
  2. Click User list in the Special pages link list.
  3. Search for your User name and then click on it.
  4. On your page, add some sections as given below, as it is your profile on the OpenOffice Wiki;
    • About yourself
    • OpenOffice and you
    • Your contributions
    • Work in progress
    • Any future plans?
    • Reference (optional)
    • Contact

So, this is somewhat a template, for creating a profile. You may or may not need to follow this template, you may have sections of your choice. This is done to make a profile in a uniform way for all the new users.


Adding Comments

Important comments should be announced on the mailing list dev@documentation.openoffice.org to be sure that they get noticed.

To add a comment to a page

  1. Click the Discussion tab on the top of the page.
    • If you are starting a new topic click on the + sign to the right of the edit tab at the top, fill in the subject line and write your comment in the main text box.
    • If you want to add a comment to an existing discussion leave it after the existing comments and indent it by putting one or more colons (:) at the beginning of each paragraph.
  2. Sign your username with four tildes (~~~~). You can do this automatically with the signature with timestamp button on the toolbar.
  3. Click Save Page.

To learn more about comments see the Mediawiki help about talk pages

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. Every subpage is automatically linked back to the main page.

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
Subpage Description
Documentation/Dashboard High-level tracking of documentation sub-projects and content deliverables
Documentation/Administration Guide Guide that describes how to administer an OpenOffice.org network installation
Documentation/FAQ Collection of FAQs.
Documentation/How Tos Link collection of How Tos
Documentation/OOoAuthors User Manual Collection of User Guides from OOoAuthors
Documentation/Tutorials Tutorial collections from different contributors
Documentation/Samples, Templates and Clipart Sub-project page in order to provide usable templates for business and personal use (draft)
Documentation/Setup Guide Sub-project page in order to provide a guide through the setup process of OpenOffice.org (draft)
Documentation/BASIC Guide Guide that provides an introduction to programming with OpenOffice.org Basic


Creating new Pages

Documentation caution.png Before creating a page make sure that there is not already an existing page with a similar topic.
  • If the new page can be a subpage of an existing page simply go to the existing page and create a link to the new page. After saving the page with the link you can click the link and start writing on your new page.
  • If you want to create a really new page for the Documentation project, you can use the wiki's URL for creating a new page. You should observe the wiki page tree when you create a new page in this way. The URL to a wiki page is then something like this:
    http://wiki.services.openoffice.org/wiki/documentation/Article

Template:Documentation/Note

For more information about new pages see the Mediawiki help about new pages

Using Categories

The Categories that are assigned to a page are usually listed at the bottom of the page. Click on a Category, and you will view a topic page with all the pages that have been classified in that Category. This way, a Category tag in a page gives you the opportunity to look up related contents. The bigger the page the more Category tags might be inserted

To add a Category tag to a page

  1. Click Special pages in the toolbox on the left side.
  2. Click Categories in the Special pages link list.
  3. Choose a Category name that makes sense, and apply it by adding at the end of the page.
Documentation caution.png Do not create duplicate Categories for the same topic. Each Category must be unique. Otherwise it will be difficult to use the Categories for searching the wiki.

Look at MediaWiki Help:Categories if you want to know more about Wiki Categories.

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

  1. Create a Category named after the current chapter.
  2. Add the new Category tag to all pages of that chapter
  3. Add the Category tag for the book to the newly created Category page.

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 at the Templates help 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}}

Docbanner.png
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|Always switch off power before opening the case.}}

Documentation caution.png Always switch off power before opening the case.
Template:Documentation/CheckedAccuracy Marks up pages that have been reviewed for accuracy.

Be sure to add name and date of review by adding a ~~~~ as parameter: {{Documentation/CheckedAccuracy|~~~~}}

Template:Documentation/DraftPage Marks up pages that are in a draft state

{{Documentation/DraftPage}}

Template:Documentation/DraftPage
Template:Documentation/hbar Used to draw horizontal bars for simplistic bar charts

Template:Documentation/hbar Template:Documentation/hbar Template:Documentation/hbar

Template:Documentation/HelpNeeded {{Documentation/HelpNeeded|Check the spelling}} Template:Documentation/HelpNeeded
Template:Documentation/Imported {{Documentation/Imported|author=Author Name|contributors=Contributor Names}} Template:Documentation/Imported
Template:Documentation/Linux {{Documentation/Linux|Linux related content}} Template:Documentation/Linux
Template:Documentation/MasterTOC This is the master template that is used to create tables of content. For usage click the template name.
Template:Documentation/NeedsRework {{Documentation/NeedsRework}} Template:Documentation/NeedsRework
Template:Documentation/Note {{Documentation/Note|Notable stuff}} Template:Documentation/Note
Template:Documentation/OOo Displays an OpenOfiice.org logo

{{Documentation/OOo}}

Template:Documentation/OOo
Template:Documentation/Outdated {{Documentation/Outdated}}
Template:Documentation/PDF {{Documentation/PDF}} Template:Documentation/PDF
Template:Documentation/PRODUCTNAME A variable for displaying the string OpenOffice.org.

{{Documentation/PRODUCTNAME}}

Template:Documentation/PRODUCTNAME
Template:Documentation/Tip Takes sections containing tips, i.e. useful non-crucial information.

{{Documentation/Tip|Right-click opens the context menu}}

Template:Documentation/Tip
Template:Documentation/*TOC Several tables of content based on Template:Documentation/MasterTOC used in guides. See, for example, the Basic Guide TOC
Template:Documentation/Windows {{Documentation/Windows|Windows related content}} Template:Documentation/Windows
Template:Documentation/FromForum {{Documentation/FromForum}} Template:Documentation/FromForum

Graphical Content

Before you can insert your well prepared image in a wiki page you have to upload it. In the sidebar, under toolbox, click Upload file.

General guidelines for images are:

  • Use the image description page to describe an image and copyright status (if any).
  • Use a descriptive and unique title.
  • 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.
  • If possible, do not pre-scale the images you are uploading. Use the MediaWiki image thumbnail feature to scale the image.
  • Edit the image if necessary to make sure that the important part is clear and visible.
  • 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.
  • JPG is usually best for photos, SVG, for icons, logos etc, and PNG for screen captures. Try not to use BMP.

When you place the image on a page 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

File:image.png
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.

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

An example image caption
  • How to handle image and table numbering?

Linking

Although the editing window offers assistence in writing internal and external links look at the MediaWiki help page about links for a better understanding of how links are working in wikis.

There is another MediaWiki help page if you need some examples.

When creating link text consider the guidelines for using links in our style guide.

General Editing Work

Editing is only possible after login. You can start editing the whole page after clicking the edit tab at the top. But usually it is more comfortable to edit individual sections of a page by clicking one of the [edit] links on the right side. If you make changes, please consider the rules of the style guide to assure a consistent writing style. Click the Show preview button before you save the page finally.

Fixing inappropriate, inaccurate, or outdated content

Contents that are not up to date are usually marked by one of the following labels:

Template:Documentation/NeedsRework You can find a collection of articles with the latter label if you click on Pages that Need Help! on the Wiki main page.

When you have selected an article to work on

  1. test whether the described procedures are still valid for the current version of OpenOffice.org.
  2. log in and make the necessary corrections.

This works best when you open two tabs in the browser, one for reading the procedures and another for editing.

When you have finished, remove the above label(s), mark the page with the label "Checked for technical accuracy" (as described in the Templates section above), and click Save page.

Fixing minor errors and typos

If you detect minor errors like typos, just log in and edit the article. Before clicking on the Save page button you might check the This is a minor edit box above.

Fixing graphics and screenshots

Fixing Style and Language

Articles that need improvement in style and language might be recognized by the following labels: Template:Documentation/HelpNeeded Template:Documentation/NeedsRework You can find a collection of articles with the latter label if you click on Pages that Need Help! on the Wiki main page.

To improve such an article, just log in, click on the edit tab and make the necessary corrections. Then remove the label(s) and click on Save page.

Linking to localized pages

Validating Content

Fixing Spam /Deleting Pages

If you detect spam you can send a mail to dev@website.openoffice.org.

There is also a list with Wiki Sysops (people who can delete pages). If you want to have pages deleted, you can either ask someone from that list, or better, add the Wiki Syntax {{delete}} anywhere on the page you want to be deleted. This will add the page to the "Candidates for speedy deletion" category, and the page will be deleted by someone with Sysop privileges, or by WikiBot maintenance.

Working on FAQs

Every question together with its answer is displayed on one single wiki page.

If you want to insert a new FAQ:

  • Select a FAQ section on the main page of the Documentation Wiki. In Writer you have to select another subpage until you reach a final FAQ section.
  • Click Add New FAQ
    A new wiki page will be created and preloaded with a template for a Q/A pair:
{{{DISPLAYTITLE: (INSERT FAQ TITLE)}}

<section begin=question/>
<INSERT QUESTION>
<section end=question/>

<section begin=answer/>
<INSERT ANSWER>
<section end=answer/>

[[Category:Documentation/FAQ/<INSERT FAQ SECTION>]]
  • Replace (INSERT FAQ TITLE) with the title of the FAQ as displayed on the page. This may be a short version of the question or the question itself.
  • Replace <INSERT QUESTION> with the actual question.
  • Replace <INSERT ANSWER> with the actual answer
  • Replace <INSERT FAQ SECTION> with the current FAQ section name. This category assignment determines where this wiki page will appear. Please use the following section names:
FAQ section section name in category
General General
Installation Installation
Word Processing Writer
Automatic Functions Writer/AutomaticFunctions
Document Management Writer/DocumentManagement
Formatting Pages and Docs Writer/FormattingPagesAndDocuments
Formatting Text Writer/FormattingText
Graphics, Frames & Objects Writer/GraphicsFramesObjects
Indexes, Tables of Contents Writer/IndexToc
Printing and Mail Merge Writer/Printing
Spreadsheets Calc
Drawings Draw
Presentations Impress
Formula Editor Formula
Database Databases
Macros Macros
  • Click Save Page

Working on How Tos

If you want to create a new How To

  1. Go to the How Tos section and open the edit window.
  2. Identify the adequate subsection and enter the title of your How To as a link.
  3. Click Save Page to make the link visible.
  4. Click the link to your How To and start writing by using the rules of the style guide. If you are not sure about how to implement the style guide, have a look at the Writer How To Getting a Picture Into the Gallery.

Template:Documentation/Note


If you want to revise existing How Tos, watch for the label "This article needs to be checked for accuracy and style."

  • Test whether the described procedures are still valid for the current version of OpenOffice.org,
  • check whether the rules of the style guide are applied,
  • check for grammar and spelling mistakes,

and make the necessary corrections in the edit window.

When you have finished, mark the page with the label "Checked for technical accuracy" as described in the Templates section above, and click Save page.

Do not forget to notify dev@documentation.openoffice.org about your work on the How Tos.

Working on Guides

Localizing Content

Content on this page is licensed under the Public Documentation License (PDL).
Personal tools