Relating to Site Structure

• Site is built around two main tutorials titled the "Quick Start" and "Full Tutorial." 
  
• The "Quick Start" is intended as a guide for users that merely need to login to edit existing pages.  It is also intended as a pre-requisite for the "Full Tutorial."  The Quick Start tutorial should be skimmable and understandable in 30 minutes or less.
  
• The "Full Tutorial" is for site administrators and should pick up where the "Quick Start" leaves off.  The start of the "Full Tutorial" needs to mention that readers should have already read the "Quick Start" before going forward.
  
• Both the "Quick Start" and "Full Tutorial" are intended to be the first two sections people will encounter and are to be trajectory-based (i.e. step by step guides), rather than all encompassing references or brief, task-based instructional how tos.
• Outside of the "Quick Start" and "Full Tutorial", the reminder of the site is made-up of task-based materials including how tos, cookbook guides, frequently asked questions, and glossaries of terms.  Where possible, the PloneHelpCenter custom content types of FAQs, Glossary Entries, Tutorials, etc. should be used and contributed to the PloneHelpCenter section of LearnPlone.
  

Relating to Writing of Content

• Name each tutorial topic with the someone wants to accomplish, rather than the "feature" of the software they will learn (e.g. "Adding New Pages to the Site" rather than "The Add Item menu", "Setting Permissions" rather than "Sharing Tab").
• Use the Description field to tell users why they should read this topic. For example, in "Publishing Content Items" the description could be "Content items you add or edit don't appear to the public until you publish them." In "Creating a Default Page" it could be "By default, folders on your site display a list of their contents. To define a custom landing page instead of a list of objects, follow these steps."
• Specific references to organizations providing Plone services are not to be embedded within the main content.  Instead of using specific text like "email us at info@domainname.org", use text like "Need help? Contact us via the information at the bottom of this page."
  
• All content on the LearnPlone website must be written describing a stock Plone website. 
  
• All content should be tagged with any and all relevant Plone versions, so that this site can become a resource for users of past, present, and future versions of Plone.
• Where relevant, this site should be referred to as "LearnPlone", rather than learnplone.org.  This is contextual for those visiting the site via anything from http://learnplone.org to http://learnplone.ifpeople.net to http://learn.plone.org.
  
• It should be noted that many users will come to the site with heavily customized and extended Plone websites.  It should be prominantely noted that documentation is not relevant for all Plone sites and that when in doubt, the user should use the contact information at the bottom of the page.
• Internal URLs should be relative, rather than absolute, so that appropriate theming is maintained when browsing around from section to section of the site. 
  
• Details about a particular organization should not be included within the main area of a page.  Always refer to contact information at the bottom of a page.
  
  

Relating to Screenshots

• Use at least 1-2 screenshots per page to communicate complicated tasks and to accomodate visual learners [Good example of documentation with nice images: http://opensourcearticles.com/articles/plone/english/part_01]

• Images should be max 600 pixels wide and should have an alt attribute that clearly describes the contents of the picture.
• Screenshots are to be created from a stock 2.1.x website without any customizations to functionality or design in order avoid confusing LearnPlone.org's intended audience.
  

Relating to the Styling of Content in Order to Aid in Skimability

• Use the "Formatted" class to designate exact text that's used in the Plone interface (i.e. "Allow Comments?", "Add to Folder")
• Glossary Terms in use in normal pages
  • Use <a class="glossary"> to designate terms that are in the glossary
  • include an anchored/direct link to its definition in the glossary
  • use <a> tag's "title" field to say:
    • "Define this term in the glossary"
    • OR "Definition: <the term's def>"
• Use <div class="pullquote"> (note: add to style menu) for items you'd like used as pull quotes on the page
• Frequently use ordered and unordered lists to increase skimability and define sequential steps

Relating to the Jargon-Free Content

The following is a list of frequently used Plone and/or web terms that are jargony and should be avoided (though they may have an entry in the glossary) for LearnPlone.org's intended audience.  Proposed alternatives are suggested:

• portal --> Web site
• WYSIWYG --> Content editor (and link to glossary def)
• Product --> Add-on feature
• index page --> Landing page (and link to glossary def)
• RSS --> Syndication/News Feed (and link to glossary def)
• Kupu/Epoz --> Text editor
• Permissioned users --> Site editors
• Functionality --> Feature
• Document --> Page