Docs Style Guide

Revision as of 00:25, 10 September 2011

Lets talk about style!

PageLines, like yourself, has it's own style. This page will discuss how to keep this style consistent in all the pages in the Docs.

General Style

Conversational. Write like you would talk. No one wants to read another dry software manual. Keep it technical but be upbeat and fun when appropriate.

Use the present tense and avoid passive voice.

Avoid using 10 words when 3 will do. Keep it concise and it will communicate better.

PageLines belongs to the community, tell it that way. Use PageLines instead of 'I, we, our" its not them vs us its all of us!

When using PageLines on WordPress to do screenshots and videos for the Docs, please use a clean, localhost install of PageLines on WordPress. All settings should be reset to default in-between writing new How-Tos.

Type of Pages

There are two main categories of articles.

1. Glossary Terms
2. How-To Guides

Glossary Style

This is a simple definition of the term.

• Example:

All Glossary items will be organized in alphbetical order on the Glossary page.

If your definition gets long enough to use a table of contents, it's probably not a definition. Keep it clear and concise.

How-To Guide

This is an in-depth walkthrough of how to use a specific function or complete a task using PageLines.

How-tos will consist of a text walk-through with supporting images. Take screens shots as you go and reference the images in your writing.

Videos should be created of each walk-through once the page is complete and the text can be used as a script for the video.

Referencing Tools

When referencing the use of tools like FTP clients or CSS editors. Reference the section on the [[Tools]] page rather than the tool itself. All suggested tools should be included and described on the Tools page.

Image Styles

• DO NOT use spaces in the file names. Dashes are OK.
• Crop out all browser items in your images
• Images should be no wider than 725 pixels.
• If possible keep your image size below 150k.
• Please use jpg or png formats.
• If you upload an image by mistake, ask an admin to remove it.
• Name your images as "pagetitle-description"
  • Ex: usetemplatesetup-overview.jpg
  • Markup: [[File:wiki.png|thumb|alt=Puzzle globe logo|Wikipedia Encyclopedia]]

Video Styles

• Use a friendly conversational tone in your voice
  • Be happy and have a good attitude, smile when you are recording and it will come through the audio
• Text pop-ups should be a transparent black box on the bottom of the video, using the Georgia font
  • See screenshots of acceptable text boxes here
• Transitions should be fades
• No gradients, no added colors
• Example:

Page Structure

The first header inside of any page should be an h2 header using ==Header==. Single = signs are reserved for the page title only.

Hierarchical organization

• Avoid unnecessary layers; they make documentation hard to find and hard to follow. For example, consider that in a book, the appendices are on the same level as "chapters" of the book.
• Avoid duplication; it is better to link to existing documentation about a topic, rather than duplicate it (or nearly duplicate it) in a second location.
• Test the structure: Start at the top, and select a path that would lead a new user to your topic. If there is an absence of a clear path, or multiple plausible paths, submit an issue.
• Consider forum requests: If the documentation page exists, but a forum inquiry indicates it couldn't be found, consider whether the documentation structure is unclear for a new user looking for the topic. Rather than just providing a link to the page, provide the path to the page as well.

Hierarchy example:

Bad:

Main topic
--Theory
--Implementation
--Examples
----Example one
----Example two
--Special circumstances
----Case one
----Case two

Good:

Main topic
--Theory
--Implementation
--Special circumstance considerations

In this example, the examples and Special circumstance cases are not a part of the navigation structure but rather bullet points in the header.