Liferay Editorial Guidelines
by Rich Sezov, Knowledge Manager for Liferay
Table of Contents [-]
- Hierarchical Design
- Text Conventions
- Common Grammatical Mistakes
- Proper Etiquette for Wiki articles
Now that the documentation is on Github (https://github.com/liferay/liferay-docs), Liferay and the community can collaborate on documentation. To make this collaboration successful, it is important that all documentation 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 documentation adhere to the following editorial conventions.
Hierarchical Design #
The official documentation has 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 see more easily 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. Markdown gives you six levels of headings (the same as HTML), 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.
Heading intros and outros #
Use segues to introduce new headings and to sum up completed ones. For example:
...that's how you configure Liferay. Next, we'll look at what it takes to make it sing a song.
Singing a Song
You'd think that making Liferay sing would be hard, but it is in fact easy. All you have to do....
Text Conventions #
There are several text conventions that will help to ensure a consistent documentation style. Please follow these conventions when entering documentation.
Code in Text #
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 a code style 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 Using Liferay book so that it looks like this:
Set this property to
falsefor easier debugging for development. You can also disable fast loading by setting the URL parameter
Always set off code so that it is clear it's code and not text. This makes it so that people can easily copy/paste from the documentation) whatever code you are providing. Of course, make sure your code works.
File Names #
When you need to refer to a file name, put the file name in a code font as well.
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
Quotation Marks #
It's much better to set off properties, classes, or code blocks with a code style 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.
Programmers are used to writing code, not prose. Because of this, programmers like to put periods, commas, and other punctuation outside the quotation marks, which is incorrect punctuation--but good programming syntax. If you do need to use quotes for something, please remember the punctuation 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.
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 is one place where we want to use bold: field Lists.
When explaining a form that users can fill out, use bold for the field names.
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:
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.
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. This sounds like common sense, but you'd be surprised at how many people just write something and send it off like it's email. To get good prose, you have to go over it several times.
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 apostrophe 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, in order to try to be fair to the genders, alternate genders as they go ("If you configure this permission for the user, she cannot access the resource."). That's also correct. Others try to make the sentence plural ("If you configure this permission for users, they cannot access the resource."). Again, this is 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.
Proper Etiquette for Wiki articles #
In general, the Wiki is a place for communicating information in a quick, organized, and business-like fashion. As such, a few things to keep in mind:
- Format long articles with headings and introductions. Also, try to have clear and concise.
- Avoid abusive talk and indirect criticism. We are here to learn and share. Do highlight problems and other concerns. But please do so out of respect to other editors and readers and not simply to vent your feelings.
- Please do not use the Wiki to advertise a company or product. This is a place for knowledge transfer, not a marketplace.