Documentation/Dashboard/Wiki Editing Policy
Template:Documentation/Banner Template:Documentation/DraftPage Template:Documentation/BeingEdited
This article helps you to contribute effectively to the Documentation part of the wiki.
Contents
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
Subpage | Description |
---|---|
Documentation/Dashboard | |
Documentation/Administration Guide | |
Documentation/FAQ | |
Documentation/How Tos | |
Documentation/OOoAuthors User Manual | |
Documentation/Tutorials | |
Documentation/Samples, Templates and Clipart | |
Documentation/Setup Guide | |
Documentation/BASIC Guide |
Using Categories
Look here if you are unfamiliar with Wiki Categories.
A simple example of how to use Categories in Wiki books:
- Create a Category named after the current chapter.
- Add all pages of that chapter to the chapter Category.
- 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
- wrong:
- 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|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 |
Graphical Content
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.
- 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.
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]]
- 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
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.
When creating link text consider the guidelines for using links in our style guide.
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
Every question together with its answer should be displayed on one single wiki page. If this is not the case you may want to help with reorganizing the FAQs.
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
- Go to the How Tos section and open the edit window.
- Identify the adequate subsection and enter the title of your How To as a link.
- Click Save Page to make the link visible.
- 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.
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.