by Rich Sezov, Knowledge Manager for Liferay

Introduction

The Liferay wiki is a place where Liferay and the community can collaborate on documentation. Because the documentation contained herein is sometimes later used as official documentation, it is important that it all be formatted consistently. Otherwise, time is wasted reformatting the docs for publication--time that could be used to create new or improve existing documentation.

For these reasons, we ask that those contributing to the wiki adhere to the following editorial conventions. What follows are various conventions we use in official documentation that we would like to see in wiki articles as well.

Hierarchical Design

Most wiki articles and the official documentation have a hierarchical design. This means that the text is divided up into small sections that have headings above them. This breaks up the text and allows the reader to more easily see the overall organization of the documentation. It has the added benefit of allowing the reader to skip to the section he or she wants to read most (because we--even those of us who write it--all know that reading documentation is not necessarily everyone's favorite task).

Sections should be kept as short as possible, by breaking them up further into subsections. The Wiki gives you six levels of headings, which should be sufficient for all your needs.

Headings and Subheadings

Headings and Subheadings should follow an outline format. This means that if they're in a hierarchy, there should always be at least two children: otherwise, you don't have a true hierarchy. I have deliberately violated this rule so that this particular subheading itself can be an example of what not to do.

Table of Contents

The nice thing about breaking up content into sections is that our tools can parse those section headings and build a nice table of contents out of them. You can see this in our wiki articles and in our official documentation. When writing articles, always include the Table of Contents tag (<<TableOfContents>>) at the top of your article.

Text Conventions

There are several text conventions that will help to ensure a consistent documentation style. Please follow these conventions when entering documentation into the wiki.

Italics

General Notes

Programmers love to put stuff in quotes when they're doing documentation, probably because it's similar to code. Code looks like this:

String myString = "Hello there!";

Consequently, many programmers therefore write documentation that looks like this:

    # Set this property to false for easier debugging for development. You can
    # also disable fast loading by setting the URL parameter "css_fast_load" to
    # "0".   

Please do not do that for documentation. Use Italics instead. We are not writing code; we are writing instructions for human beings to be able to write code or use our software. Obviously, if you are documenting something in a text file in the product itself, you can't do this, and the example above was taken from Liferay's portal.properties file.

This text was reformatted in the Liferay Administrator's Guide so that it looks like this:

Set this property to false for easier debugging for development. You can also disable fast loading by setting the URL parameter css_fast_load to 0.

See how the properties are set off by using italics instead of quotation marks? This has two benefits: the text is marked so that people pay more attention to it, and there is no ambiguity as to whether or not to include the quotation marks when copying and pasting these values. And here's one way you can tell a programmer wrote this: the original has the period outside the quotes at the end of the sentence, which is incorrect punctuation--but good programming syntax. If you do need to use quotes for something, please remember the period always goes inside the quotes.

Introducing Concepts

If you're introducing a concept, italicize the concept the first time you use it. Thereafter, you don't need the italics.

Example: One of the primary ways of extending the functionality of Liferay Portal is by the use of plugins. Plugins are an umbrella term for installable portlet, theme, layout template, and web module Java EE .war files. Though Liferay comes bundled with a number of functional portlets, themes, layout templates, and web modules, plugins provide a means of extending Liferay to be able to do almost anything.

Notice the italics on plugins, portlet, theme, layout template, and web module the first time the terms are used, but none when the terms are used after they are introduced.

UI Elements

When you're telling the user to click on something in the UI, italicize it.

Example: Click the Save button to continue.

File Names

When you need to refer to a file name, italicize the file name.

Example: You will want to use the Software Catalog portlet if you will have multiple users submitting portlets into the repository, and if you don't want to worry about creating the liferay-plugin-repository.xml file yourself.

Bold

Bold is used sparingly in the documentation. Why is this? Because too much bold is distracting. The reader's eye is drawn to bold text more than to anything else. All of the headings are bold anyway, so we don't want to use it very much in the body text itself. There are, however, several places where bold is used.

Introducing Portlets

Like Introducing Concepts in the Italics section above, we introduce portlets with bold text and thereafter just capitalize the names.

Example: The Enterprise Admin portlet is used for most administrative tasks.

Field Lists

When explaining a form that users can fill out, use bold for the field names.

Example:

Name: Enter the user's name.

Address: Enter the user's address.

Bullet Points

Bullet points are strange animals. They can be lists of things. They can be lists of arguments. Here's a good rule for bullet points: if it's a sentence, use a period. If it's not a sentence, don't.

Examples: Don't use a period for bullets that are not sentences, like:

• Shoes
• Pants
• Shirt

Use a period for bullets that are sentences, like:

• Roll your mouse over the Dock and click Sign In.
• Enter your email address and password.

Code

Always set off code so that it is clear it's code and not text. The wiki makes this really easy with the preformatted tag, which is the bottom-most tag listed in the Syntax Help box on the right of the edit screen. This tag works inline, like this, or set off

like this.

This makes it so that people can easily copy/paste from the wiki (or the PDF version of the documentation) whatever code you are providing. Of course, make sure your code works.

Common Grammatical Mistakes

We all make grammatical errors sometimes. I'm sure that even J.R.R. Tolkien had to correct some grammatical errors before publishing Lord of the Rings. What separates the men from the boys (or women from the girls) here, though, is whether or not you are willing to take a look at your text and find those grammatical errors to which you are prone (See? I didn't end that sentence with a preposition--even though that's not always wrong). You can then try to be more aware of those errors as you write and thereby avoid them. It also helps to read your text after you have written it. Yes, this is a pain, but it's how good prose is written.

What follows is a list of common grammatical mistakes.

It's and Its

This one is easier than it looks, even though most people give up and always use it's. Why they choose the one with the single quote is beyond me.

It's: This is short for "it is." So when you're about to write an its or an it's, ask yourself: do I mean "it is" here? If so, use the single quote. If not, see below.

Its: This is always possessive. The cat blinked its eyes.

Subject Agreement

Your subjects' references must always agree in a sentence. You can't have one be singular and another be plural. For example, you never say, "If you configure this permission for the user, they cannot access the resource." You have to say, "If you configure this permission for the user, he or she cannot access the resource." Since you're talking about a single user, it's either he or she, but not they. Some people pick one ("If you configure this permission for the user, she cannot access the resource.").  That's also correct.

Notes on Commas

Commas have several elements which can be confusing. Here are some tips to help you be successful with commas.

Conjunctions vs. Compound Verbs

You only use a comma after a conjunction (i.e., "and," "or," "but," etc.) if it is separating two independent clauses. If you have a compound verb, you don't need a comma. So you'd use a comma with "Click on the button, and the portal will refresh." But you wouldn't use a comma with "Select option three and click save." In the first instance, you have two independent clauses; in the second, you have a compound verb ("select and click"). One easy way to tell which one you're dealing with is to find the subject(s). If you have two different subjects, you have two independent clauses. If you have one subject sharing two verbs, you have a compound verb.

So in our first example, our two subjects were you and portal (the you is understood as (You) click on the button...). So we need a comma there, because we're separating two independent clauses.

In our second example, we had one subject: you. The subject of the sentence is doing two things: selecting and clicking. We therefore have a compound verb and don't need a comma.

Comma Splices, Semicolons, and Em Dashes

Most people I've talked to have no idea what to do with a semicolon (;). Java programmers, of course, know what to do with it: you end a statement with it! (That's a poor attempt at humor.) Seriously, though, many people wind up using a comma in a place where you should use a semicolon, and that is when you're separating two independent clauses (i.e., sentences). Consider the following example:

Don't try doing it all yourself, it's better to work as a team.

That's a comma splice. You're splicing together two complete sentences with a comma:

Don't try doing it all yourself. It's better to work as a team.

While a comma splice is incorrect punctuation, using a semicolon in the same place is a drop-in replacement for a comma splice, as a semicolon is used to separate two independent clauses:

Don't try doing it all yourself; it's better to work as a team.

If you write it this way, your punctuation is correct, and you have just become one of those few who know how to use a semicolon!

It's also important to note that the em-dash (--) can also be used in this way:

Don't try doing it all yourself--it's better to work as a team.