Docs

Docs Style Guide

[edit] Please Note

These docs are now deprecated, we have a new Support area located here

(Difference between revisions)
(→Type of Pages)
(→Type of Pages)
 
(4 intermediate revisions by 2 users not shown)
Line 22: Line 22:
 
# How-To Guides
 
# How-To Guides
  
−
=== Glossary Style ===
+
'''Glossary Style'''
  
 
This is a simple definition of the term.
 
This is a simple definition of the term.
Line 31: Line 31:
 
If your definition gets long enough to use a table of contents, it's probably not a definition. Keep it clear and concise.
 
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 ===
+
'''How-To Guide'''
  
 
This is an in-depth walkthrough of how to use a specific function or complete a task using PageLines.  
 
This is an in-depth walkthrough of how to use a specific function or complete a task using PageLines.  
Line 50: Line 50:
 
* Images should be no wider than 725 pixels.
 
* Images should be no wider than 725 pixels.
 
* If possible keep your image size below 150k.
 
* If possible keep your image size below 150k.
−
* Please use jpg or png formats.
+
* Please use png formats.
 
* If you upload an image by mistake, ask an admin to remove it.
 
* If you upload an image by mistake, ask an admin to remove it.
 
* Name your images as "pagetitle-description"
 
* Name your images as "pagetitle-description"
 
** Ex: usetemplatesetup-overview.jpg
 
** Ex: usetemplatesetup-overview.jpg
 
** Markup: <nowiki>[[File:wiki.png|thumb|alt=Puzzle globe logo|Wikipedia Encyclopedia]]</nowiki>
 
** Markup: <nowiki>[[File:wiki.png|thumb|alt=Puzzle globe logo|Wikipedia Encyclopedia]]</nowiki>
 +
See [[Screenshot Guidelines]] for more info
  
 
'''Video Styles'''
 
'''Video Styles'''
Line 61: Line 62:
 
** Be happy and have a good attitude, smile when you are recording and it will come through the audio
 
** 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
 
* Text pop-ups should be a transparent black box on the bottom of the video, using the Georgia font
−
**  [[video text boxes|See screenshots of acceptable text boxes here]]
 
 
* Transitions should be fades
 
* Transitions should be fades
 
* No gradients, no added colors
 
* No gradients, no added colors
 
*Example:
 
*Example:
  
−
==Page Structure==
 
  
−
The first header inside of any page should be an h2 header using <nowiki>==Header==</nowiki>. Single = signs are reserved for the page title only.
+
[[Category: New Page]]
−
 
+
−
'''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:'''
+
−
<pre>Main topic
+
−
--Theory
+
−
--Implementation
+
−
--Examples
+
−
----Example one
+
−
----Example two
+
−
--Special circumstances
+
−
----Case one
+
−
----Case two</pre>
+
−
 
+
−
'''Good:'''
+
−
<pre>Main topic
+
−
--Theory
+
−
--Implementation
+
−
--Special circumstance considerations
+
−
</pre>
+
−
 
+
−
In this example, the examples and Special circumstance cases are not a part of the navigation structure but rather bullet points in the header.
+
−
 
+
−
 
+
−
[[Category:New Page]]
+

Latest revision as of 03:49, 30 November 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 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]]

See Screenshot Guidelines for more info

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
  • Transitions should be fades
  • No gradients, no added colors
  • Example:
Retrieved from "http://www.pagelines.com/wiki/index.php?title=Docs_Style_Guide&oldid=3300"