What This How-to Covers

• Documentation life-cycle
• General Tips
• Titles
• Descriptions
• Body text
• Images
• Text format
• Versions
• Sections
• Audiences
• Comments
• Contributors
• Keywords
• Redirection Tool

Documentation life-cycle

Consider first, the culture of community documentation. The normal workflow is:

1. Author adds documentation,
2. Reviewer publishes documentation,
3. User reads documentation,
4. User has question/correction,
5. User adds comment,
6. Author gets automated email triggered by user comment,
7. Author reads comment,
8. Author incorporates comment in documentation, if relevant and useful. Author can edit owned content in-place after initial publication. No need for another submit/publish cycle,
9. Author removes the comment,
10. The flow starts at (3) again.

General Tips

• Do not approve your own content. It should always be reviewed by someone else before it is published.
• Individual Product documentation should not be here. It belongs together with the Product itself, since Products can now have their own help centers.
• Try to stick to the Plone terminology - it's "portlets" - not "boxes," "views" - not "tabs," etc..
• Make sure you test the documentation before approving it. The author might have left out a step or a non-obvious explanation. Perform the actions listed in the text, and make sure it works the way it should afterwards.
• If you find content that you are not 100% sure what is about, leave it to somebody else to review. You shouldn't review content you aren't familiar with, If you are a UI designer, you might want to refrain from writing the LDAP how-tos.
• Documentation that does extremely heavy customizations to Plone should probably not be here. Such content should either be in a Product or in a detailed Tutorial at the very least. We don't want to encourage people to make their sites unmaintainable.
• Documentation that is essentially consist of a bunch of template code listings (conversion scripts, very specific customizations, etc.) should be Product downloads, not How-tos or Tutorials. If it has an educational value in that you learn a lot from how things are done. That is, there are more than just code listings. Typically a Tutorial with code examples - it's OK.
• Documentation that teaches stuff that is documented elsewhere ("How to insert an iframe in your web page," etc.) should not be here. If it has particular relevance in Plone, it's fine. But we can't document how HTML/CSS works or similar. Stuff like, "How to set up Plone on Apache," is, of course, relevant.

Titles

• Should be as concise as possible.
• No need to include "How to..." or "Tutorial" in the title. This is obvious from the context anyway.
• Plone now uses automatic "title to id" short name generation. The short name for a piece of content, used in the URL for the content, is made automatically by lower casing the title and substituting blank space and punctuation with hyphens. But sometimes things need to be slimmed down a bit to remove words like "a," "the," etc..
• If you discover an already published document with a bad short name (autogenerated; way too verbose or irrelevant; "CamelCasing"), use the Redirection Tool instructions below to rename it and create an alias from the old location to the new one.

Descriptions

• Should be short and to the point.
• Remember, descriptions appear in overview listings.

Body text

• Pay attention to proper punctuation, casing, grammar, and spelling.
• Overly long paragraphs should be split up into several paragraphs.
• Long documents should have descriptive headlines (and/or multiple pages in the case of a Tutorial).
• Pre-formatted text (code examples, etc.) should work in 800x600 - which normally means you have to trim the width of the code to below 80 columns. Reformat Python and ZPT code to fit this, but make sure the code works when cut/pasted. In Python, you normally insert \ at the end of lines to continue on the next line. HTML normally doesn't care about whitespace.

Images

• All screenshot images should look like default Plone (unless illustrating skinning).
• All images should have .jpg / .png / .gif extensions for caching reasons.
• No off-site images. Images should reside inside the How-tos/Tutorials folders. If an external web site is down, the documentation is useless. If plone.org is down... well, you know who to call. ;)
• Image width should be so it fits on print-outs and on a 800x600 screen when displayed. Which means no images should be wider than 600 pixels at the very most. If they are wider than that, the text will run outside the page area and be unreadable.

Text format

• HTML: Kupu is great. Use it. Hand-coded HTML is OK if you do proper XHTML, but avoid it when you can.
• STX just works. It's simple.
• reST is more powerful, but produces less desirable XHTML.
• Pick a format and stick with it.

Versions

• No version should be selected if applicable to all versions of Plone.
• Versions exist mainly to separate out things that were useful in 1.x but not in 2.x, or in 2.0.x and not in 2.1.x. Versions are not there to list all possible versions. Pick the versions that apply to your help content.
• For most stuff, it will just be extra work for the documentation team to add new versions when they come out. It's easier to go back and assign specific versions when we know that something changed — i.e. the versions mechanism is typically used to say "this used to be this way in 2.0 — it's not anymore, but we're keeping it around so you can see it if that's what you are running". It's typically used after the fact, not up front.

Sections

• If you can identify a big section missing conceptually, add it to the container.
• Try not to pollute the section space with unnecessary new section headings. If a new section is necessary, aim for a serendipitous heading consistent with the pre-existing headings.
• See if your new section name can be a minor heading appended to one of the existing major headings. Example: "Plone Setup: Installation" is an existing section name with a major and a minor heading. Your new heading might be, "Plone Setup: Site Preferences."
• Capitalize each word in a section name and separate each word with spaces. No Wiki words. No gratuitous CamelCasing. :)

Audiences

Pick just one audience for your help content. (Help content without audience will be displayed in a "for all" list, though). Having help content tagged with audiences helps slice and dice the content repository in interesting ways. Audiences are a controlled vocabulary. That is, you can only select a pre-existing audience category. You cannot add a new audience. Choose carefully.

As people will look in several categories, we should limit ourselves to just one category. They'll find it when they browse the several groups. And it keeps down the duplication in the various lists.

The best way to look at the audience is to think "who will have to change this?" Figuring out how to connect to the Active Directory will be the developer's task. Caching has a lot to do with apache and squid, so that's for the site admin (probably also the developer, but mostly the site admin). Possible audiences are:

End Users

People who view a site or contribute content.

Server Administrators

People who groom and care for the operating system and control file system access. This includes installing python and zope, apache config, squid caching, etc. Also installing products on the filesystem. Rule of thumb: you don't need a webbrowser.

Site Administrators

People who own site deployments and manage members and content. This includes managing LDAP connections and so, but not installing zope and configuring apache. You should need a webbrowser for everything in this category!

Integrators/Customizers

Graphic and UI designers; people who write simple templates and/or scripts. So if the documentation deals with templates or python scripts: yes. If you have to write actual product code in your core .py files: put it under "developer".

Developers

People who design and write Plone products and content types.

Advanced Developers

People who contribute to the core Plone codebase. (Bad name, but we'll stick with it for now. Don't make the mistake of thinking "hey, this is hard, this is not for ordinary developers".)

Comments

Comments area treated as very temporary content. Any useful info from them should be used to refactor the document itself, and then deleted. This is important. We don't want long threads of discussion going on.

Contributors

One of the best ways to help develop Plone help content is to follow Plone email support lists and chat rooms. You will notice the same questions being asked and the same answers being given repeatedly. Put those questions and answers here in the documentation folder! The questions will be repeated less. And the answers can be pointers to your documentation contributions.

• When you put someone else's answer to a problem or question in the documentation folder, credit them as a Contributor.
• To credit multiple contributors, enter their names on separate lines, one contributor per line.

Keywords

Content may be tagged with keywords on the "Edit" view of the content item. Keywords greatly assist in indexing and searching for content.

• Try to find existing keywords. The smaller the keyword vocabulary, the most useful keywords are.
• Pick multiple keywords where appropriate. Keywords are a multiple selection list.
• When adding a new keyword:
  • Capitalize the first letter of the first word only.
  • No Wiki words or CamelCase. Separate words with spaces.
  • Use plurals where appropriate.
  • Example: "Document actions"

Redirection Tool

A very useful thing to know is the Redirection Tool. It's useful for redirecting old content to new content. Example:

• /documentation/how-to/old-doc exists
• new-doc takes its place
• Delete old-doc
• Go to new-doc/redirection_form
• Add old-doc as alias (this doesn't need a path unless it is in a different folder)

It also takes care of sub-folders, so if you had old-doc/1/2, the new link will be new-doc/1/2.

This is also a good way to rename documents that have bad short names without breaking links.