This document is for authors of Spring documentation. It describes when and how to use the various document elements (headings, tables, lists, and so on) and describes best practices.
|
Note
|
A style guide is not a stylesheet. This document does not cover font faces and point sizes and other layout details. Rather, it offers advice about how to write well for Spring. The associated CSS file defines the layout details. |
|
Note
|
This guide is not meant to be an explanation of how Asciidoc works. For the syntax of how to create any particular construct in Asciidoc, see the Asciidoc User Manual. |
This style guide covers the following topics:
When writing about Spring, remember that the goal is to get information from the document into the reader’s head. Few people read technical documentation for fun or are going to admire the quality of your prose, no matter how good it is. However, if you can quickly teach them useful things, they are likely to think the documentation is wonderful.
Also, remember that people with a wide range of backgrounds and abilities use Spring. People with doctoral degrees in Computer Science and high school kids who want to join the profession both use Spring, and we need to think of them and everyone in between when we write about Spring. We also have readers from all over the world, and English is not the first language for many of them. They may be good with English, but it is never quite the same as one’s native language.
To serve all those different people well, one crucial bit of advice is to keep things simple. Prefer shorter sentences to longer sentences and shorter words to longer words. Prefer multiple short sentences to one long sentence. This document returns to each of these points in detail.
Above all, remember that the goal is to help people from all kinds of backgrounds learn to use Spring.
|
Tip
|
Remember that not everyone who reads our documentation knows Spring. Some readers are new to all of Spring. Consequently, if you find yourself writing phrases such as "as Spring usually works" or "as customary" or anything else that implies the user is familiar with Spring, rewrite that content such that the reader need not know anything about any part of Spring. Doing so often forces the inclusion of more detail and links to other content, both of which suit our purpose. |
A title tells its reader what a document is about. Ideally, it should be followed by a paragraph that identifies both the audience and the purpose of the document, so that readers can be sure they want to spend their time reading the document. The first paragraph of this document offers an example.
You should generally use title case, which means capitalizing the first letter of all significant words (all words that are not articles, conjunctions, or prepositions).
You can put code in a title. When you use code in a title, capitalize the code element as you would in the actual code. (See Source Code Listings.)
Spring technical documents do not use subtitles.
|
Note
|
The Spring standard for multi-chapter documents is to put each chapter in its own file. In other words, each chapter is its own document. |
Headings break up documents into meaningful chunks. Small documents may not have any headings. When the entire document deals with a single concept, the title may be all the heading it needs. However, most technical documents benefit from being broken into meaningful chunks.
The Spring documentation uses the various heading levels as follows:
-
Heading level 1: Indicates a major chunk within a document. Each one should be an important topic in its own right.
-
Heading level 2: Deals with something significant within a broader concept (which should be the level-1 heading above the level-2 heading).
-
Heading level 3: In larger documents, deals with something significant within a broader concept (which should be the level-2 heading above the level-3 heading). In a smaller document, this level deals with a meaningful detail.
-
Heading level 4: Deals with a meaningful detail in a larger document. This level should be avoided in small documents.
-
Heading level 5: Should be avoided. May deal with a minor detail in a large document.
Level-1 headings often contain content that could reasonably be a document in its own right. The same is sometimes true of level-2 headings. Level-3 and level-4 headings should not contain content so significant that it could be its own document. If you find that your level-3 (or, worse, level-4) headings can reasonably be documents on their own, you should consider restructuring the document. It may benefit from being split into multiple chapters or other documents.
Level-2 and Level-3 (and, rarely, level-4) headings sometimes serve as containers for collections of lesser headings. That is, the point of the heading may be to have a single heading for a number of parallel blocks of content.
|
Important
|
A heading of any level should always have a lead paragraph (and often other content) before any child headings. In other words, you should never have a heading and then a child heading without intervening content, even if that content is a one-sentence paragraph. (A one-sentence leader paragraph often occurs when a heading is a container for a number of child headings of the same level.) |
|
Tip
|
Content within level-5 headings can often be blended into the parent topic, sometimes as a list or a table and other times as an admonition or a series of admonitions. |
|
Tip
|
Ideally, a level-1 heading (and sometimes a level-2 heading) and its content can be reused either as a stand-alone document or in another document. Consequently, you should try to make the content of each of these sections make sense by itself, without the reader needing to know what comes before or after it. People often jump into a document in the middle, by searching for keywords or following links from elsewhere. Also, self-contained writing is often better writing (because it usually requires more consideration of the reader’s needs). |
Lists are a handy way to group items that share a relation. In other words, every item in the list must have something in common with the other members. You should use a list when describing the items in a single sentence becomes awkward, either because the sentence becomes overly long or because each item has its own internal punctuation.
|
Important
|
Each list should have a lead paragraph (a paragraph that introduces the list, often by describing the connection between its items). |
For example, this sentence does not need to be restructured, because it contains a simple list of red, blue, and green. However, this sentence should be restructured, because it contains a complex list of green, blue and yellow, purple, red and blue, and orange, red and yellow. The list in the preceding sentence should be written as the following bulleted list:
-
Green: Blue and yellow.
-
Purple: Red and blue.
-
Orange: Red and yellow.
In a list, you should capitalize the first letter of the first word in each list item. If you use a separator (such as the colons in the preceding example), you should generally capitalize the first letter of the first word after the separator. However, if the word in question must be a literal of some sort, capitalize the literal as you would in its natural context. For example, if your list item starts with a snippet of code, you should not change the code’s capitalization. (See Source Code Listings.)
|
Tip
|
One good reason to use a list is to reduce extra wording around the list items (by removing any introductory bits within each list item). A well written list can help readers get content from a document more quickly. |
When the order of a list matters, use a numbered list. Usually, in documentation for software development, a numbered list is either a set of instructions or an algorithm.
|
Tip
|
You should avoid numbered lists when the order does not matter, because you may needlessly force the reader to consider a detail (the order) that does not matter. |
For bulleted lists and numbered lists that are not instructions, you can embed lists within lists. Instructions follow different rules. Instructions with more than one step should always be numbered and should always be presented as a list. Also, instructions should never contain embedded lists (lists within lists). If you need to have a second set of instructions within a set of instructions, create three sets of instructions: one for the instructions down to the embedded instructions, one for the embedded instructions, and one for the remainder of the "outer" instructions. Also, each list should have its own lead paragraph. (That may seem like a lot of extra work, but it pays for itself in reduced error rates for the readers and fewer support tickets for the developers.)
Ordinary lists rarely get titles or their own headings. However, instructions often get headings.
As a rule, you should avoid using bold or italics in lists. See Highlighting.
Like lists, tables group items so that similarities and differences and key information about each item can be presented with a minimum of extra wording. Also like lists, each item in a table should share some relation with the other items. Also, a leader paragraph should introduce the table by defining the connection between the items.
You should use a table rather than a list when each item has multiple relevant attributes. If the table shows an item and one detail about each item, reformat the table into a list with a separator. (That simpler structure is faster for readers.) However, when you have two or more attributes to present for each item, use a table.
|
Tip
|
Tables are especially good for presenting sparse information (when not every item in the collection has all the attributes). The empty cells make it immediately apparent which items do and do not have the various attributes. |
As a rule, the items are the rows, and the attributes are the columns. If that is not the case, you should probably add a note to explain to the reader how to read the table.
Tables often have titles. Adding a title helps to clarify the purpose of the table and enables letting the list be stand-alone content when readers are quickly skimming a document.
The following example shows a sparse table that defines complementary colors (the items) in terms of primary colors (the attributes):
| Color | Red | Blue | Yellow |
|---|---|---|---|
Green |
* |
* |
|
Purple |
* |
* |
|
Orange |
* |
* |
In Spring’s documentation, we do not number tables.
Source code listings come in two varieties: inline and block. Inline listings are handy when you want to mention a bit of code in a sentence or a title (either the document title or a heading). Block listings let you show larger sections of code so that the reader can see the code in context and more readily understand it.
Usually, we do not remove lines from code to shorten listings. If you need to do so, you should probably have two listings, each with its own descriptive leader paragraph. If you need to highlight certain lines within a listing, you can do so by making one or more lines bold or by using callouts. When you do need to use multiple listings to show something, each listing has to have its own explanation. Do not try to use part of a sentence before a listing and continue the rest of the sentence after the listing. That creates one or more sentence fragments, which violates Spring’s documentation standard. Also, providing more detail can help to answer the reader’s questions.
|
Important
|
When you use code inline, the code’s formatting overrides any other formatting
rules, such as capitalizing words in titles and headings. Also, you should never change
code to make a word be plural. For example, if you were describing a set of Item
objects, it would be an error to write " Items " or " Item s ". Instead, you should
write " Item objects ". (Sometimes, the correct word is "implementations" or "instances"
rather than "objects".) In short, you should never indicate that something is source code
unless it can be found in the code base exactly as it appears in the document.
|
As a rule, you should be aggressive about making links to other documents, both other documents within Spring and other documents outside of Spring. If you do so, readers can more readily discover related content. Also, you should link to different kinds of content whenever appropriate. Feel free to link from a reference guide to a getting start guide, API documentation, or a tutorial and to link from any of those to the other types. If in doubt, make a link.
Similarly, you should arrange your content to be easy to use as the target of links. To that end, every level-1 and level-2 heading should have an anchor, so that other documents can include a link to that point in your document. Many other headings (level-3 and level-4 headings) should also have anchors. When you add an anchor, make sure that the content of the section makes sense without the reader having read the preceding and following content. In other words, make your sections each be complete, so that linking to them provides a good experience for readers. If in doubt, make an anchor and make the topic be able to stand alone.
|
Tip
|
One technique that helps readers find the content they want is to have links to the child headings within the introduction of a section, especially when the section contains multiple headings at the same level. The list of sections at the beginning of this document is one example. See Wording for another example. |
Images offer a way to show relationships that are either difficult to make apparent with words or that would take a lot of work for the writer to explain and for the reader to understand. Images may also be used to add visual appeal, though the content of an image should always be relevant to the content of the paragraphs around it.
As with lists and tables and the content under headings, every image should have a lead paragraph to summarize its meaning. Also, images should often have titles. For readers who may be quickly skimming the document, a title offers immediate context that helps them to understand the image’s content and may encourage them to read more of the document. Consequently, the more significant the image is to your content, the more you should consider adding a title to your image. If an image explains a core concept, you might consider giving it its own heading. In that case, it should still have an introductory paragraph and a title.
In Spring’s documentation, we do not number images.
Admonitions offer a way to provide special knowledge to the reader. Admonitions come in five varieties:
-
Note admonitions: Offer additional information that the reader may find helpful but that is not crucial to the content.
-
Important admonitions: Call out things that the reader really should know when working with the content.
-
Tip admonitions: Offer shortcuts or other details that make things easier or faster for the reader.
-
Caution admonitions: Let readers know of common errors or other issues that may slow their work or send them down an unproductive path.
-
Warning admonitions: Let readers know of risks or other issues that may cause severe problems, most notably data loss (including loss of information from databases, file systems, and version control systems).
The rest of this section contains sample admonitions, to show the admonition icons.
|
Note
|
Sample note admonition |
|
Tip
|
Sample tip admonition |
|
Important
|
Sample important admonition |
|
Caution
|
Sample caution admonition |
|
Warning
|
Sample warning admonition |
One goal of technical documentation is to make the content engaging. One way to do that is to create structures that draw the reader into reading the next part of the documentation.
To that end, the Spring documentation standard requires leader paragraphs for every list, table, code listing, and image (as well as every heading whose purpose is to be a group name for a set of child headings at the same level). Usually, the leader paragraph should be a single sentence that describes the content to come and includes the word, "following."
Similarly, using short phrases (such as "As shown earlier") or sentence adverbs (such as "Also" and "However") links one paragraph to another and both shows the relationship between the content of the paragraphs and encourages the reader to continue.
In short, you should try to show the relationships between pieces of content, even at the paragraph level, Often, it is easy to overuse the technique, but it is a worthwhile technique to keep in your writing toolbox.
Do not write sentence fragments. For example, do not write, "For example.", as a sentence by itself and then follow it with the example. Work "for example" into a complete sentence.
Use short sentences. People parse shorter sentences more quickly than they do longer sentences. You can literally get readers through your content more quickly if you use shorter sentences. You should link sentences with connected ideas by using short introductory phrases or sentence adverbs. "Also" and "however" let you continue a complex thought across two short sentences or add a contradictory detail to a preceding detail, respectively. Also, do not write whole sentences as parenthetical phrases, whether in parentheses or otherwise. Put the parenthetical content in its own sentence. Note that parenthetical phrases are often set apart with commas.
Avoid semi-colons. Used properly, a semi-colon links two independent clauses. That is, the words on each side of a semi-colon can themselves be a sentence. In those cases, you should use two shorter sentences, perhaps with an introductory phrase or sentence adverb at the start of the second sentence.
Avoid dashes. In almost every case where you can use a dash, there is another punctuation mark you should use instead. Creating a parenthetical phrase? Use commas (if the sentence does not already have commas) or parentheses. Creating a parenthetical phrase within other parenthetical content? Stop doing that and restructure the sentence into multiple simple sentences. Making separators in a bulleted or numbered list? Use colons. Making separators in a bulleted or numbered list whose items already have colons? That is the only use case for dashes.
Except when serving as a separator in lists, a colon must be preceded by an independent clause. In other words, the part before the colon must be able to be a sentence if you replace the colon with a period. Specifically, do not write, "For example:".
Put conditional phrases first. Consider the following sentence: "You can use the new
keyword if you want to make a new instance of a class." The trouble with it is that
someone has to read all of it to determine whether its content is relevant to their
situation. By putting the conditional part of the sentence first, you can help readers
through the document more quickly by letting them identify whether they care about the
second half of the sentence. To that end, the sentence should be re-written as follows:
"To make a new instance of a class, use the new keyword."
Also, note that the second sentence is shorter. "If you want" and "You can" were unnecessary (in either version). Trimming out unnecessary words offers another good way to improve the reader’s experience with the document.
In short, keep the writing simple. By doing so, you make things better for Spring’s readers.
Prefer simple words to more complex words and shorter words to longer words. To that end, avoiding words that English has borrowed from other languages (notably Latin) is often a good idea. English often has native words that mean the same thing and that are shorter and simpler and are more friendly to people whose first language is not English. See Words to Avoid or Avoid Misusuing for a few specific examples.
In addition to the fundamental advice to keep things short and simple, this section also covers the following topics:
Spring’s documentation standard uses American spelling, including the following details:
-
Words ending in "or" (such as "behavior") do not have a "u" between the "o" and the "r".
-
"Magic" does not have a "k".
-
Words ending in "ise" and "isation" (such as "specialise" and "specialisation") end in "ize" and "ization", respectively ("specialize" and "specialization").
-
And so on.
It can be tempting to highlight important words, often by capitalizing, underlining, or using bold. However, the Spring documentation standard calls for not doing so. Highlighting with any of those techniques makes the reader’s eye jump to the highlighted content, breaking the flow of their reading and forcing them to re-read sentences. In other words, highlighting slows down reading and makes the document less friendly to our readers. If you must highlight something, do so sparingly.
Mosts lists should also not have highlighting, other than to capitalize the first word of each list item and the first word after a separator within a list item. However, definition lists may have the word (or short phrase) being defined in bold, especially if the definition is on a different line than the word being defined.
|
Note
|
Code within sentences should be highlighted by using the code font. See Source Code Listings. |
- "foo" and "bar"
-
"foo" and "bar" are often used in sample code. Doing so is a mistake for two reasons. First, more meaningful examples are more helpful. For example, a line of code showing how to define two caches would be better written as
cache1,cache2than asfoo,bar. When referring to the same example later in the document, the reader is more likely to remember that the section is about caches and not have to go look at the example again. Second, "foo" and "bar" are based on a phrase that contains a curse word. While they have been used for decades, they are based on a crass joke (and often an inside joke at that, with the people using them often not knowing their history). That kind of juvenile behavior is inappropriate in good technical documentation. - "terminate"
-
Write, "end," instead. "End" is shorter and simpler. Also, "terminate" has violent connotations, and good technical documentation avoids that. Remember that people from many cultures read Spring’s documentation and that some people are more disturbed by violence than others.
- "execute"
-
Write, "run," instead. "Run" is shorter and simpler. Also, "execute" has violent connotations and is politically charged in some cultures. Good technical documentation avoids both problems. Remember that people from many cultures read Spring’s documentation and that some people are more disturbed by violence than others.
- "abort"
-
Write, "stop," instead. "Stop" is shorter and simpler. Also, "abort" has violent connotations and is politically charged in some cultures. Good technical documentation avoids both problems. Remember that people from many cultures read Spring’s documentation and that some people are more disturbed by violence than others.
|
Note
|
Using "end," "run,", and "stop" is good for two other reasons: Doing so reduces the number of Latin cognates in the document, relying on plain English words. Relying on words that have not been borrowed from other languages simplifies the document and improves understanding, especially for readers whose first language is not English. Second, if someone translates the documentation, the plain English words are easier to correctly translate. Translators often do not have programming backgrounds and are more likely to mis-translate more complicated terms. |
- "then"
-
"Then" is not a conjunction. The following sentence is incorrect: "Put on your socks then your shoes." In that sentence, "then" is an adverb, not a conjunction that can link the two parts of the process. The correct sentence is: "Put on your socks and then your shoes." Note the addition of a conjunction: "and."
- "if…then…"
-
You can nearly always drop "then" in a sentence that contains an "if…then…" clause. In English, as in Java, "then" is implied, and the meaning usually remains clear without it. Consider the following sentence: "If you are going to the store, then pick up some milk." Without losing meaning, it can be rewritten as "If you are going to the store, pick up some milk."
- "will" and the future tense
-
Avoid the future tense (often created by the insertion of "will"). Usually, the rest of the document is in the present tense. For consistency’s sake, keep it that way. Also, in some documents, it is easy to accidentally promise something, which can put the team in an awkward spot. (The latter is especially true in documents such as release notes.) Finally, sentences can often be shorter when kept in the present tense.
- "above" and "below"
-
The trouble with referring to the earlier part of the document as "above" and the later part of the document as "below" is that we have no idea where the page breaks may land when someone prints the document or renders it into a paged format (such as PDF). It is entirely possible for the "below" part referenced in the sentence to be above the current location but on the next page. Rather, write, "earlier" and "later." Also, when referring to an example that immediately precedes the paragraph, write, "preceding example."
- "just"
-
In many cases, you can remove "just" from a sentence without changing its meaning. In those cases, you should remove it.
- "very"
-
"Very" can nearly always be removed without changing the meaning of the sentence. In those cases, you should remove it.
- "simply", "easily", "obviously", and so on
-
Avoid these words and any other words that imply something is simple, easy, or obvious. For someone new to Spring, the task or issue at hand may not be simple, easy, or obvious. Remember to put yourself in the reader’s place when writing. Something that is simple, easy, or obvious to someone who works on Spring all the time is probably not any of those things to a new Spring developer. If it were simple, easy, or obvious, would they be reading the documentation?
If a number is ten or less and is a positive integer, write it as a word. Otherwise, write
it as a number. Specifically, you should write it as a number, rather than as a
word, when its value is less than zero or greater than ten, it contains a mathematical
constant, or it is anything other than an integer. The following examples are all correct:
zero, one, two, ten, 11, 12, 20, 30, -0, -1, -2, -10, -20,
0.0, 0.1, 1.0, -1.0, 2.3, -2.3, i, -i, -2i, e, -e, and -2e.
|
Tip
|
Avoid using symbols that are more complex than a single letter in the English
alphabet (such as i and e). Some rendering engines may not correctly render the
symbol, leaving the reader wondering what the symbol was meant to be (or, worse, thinking
it is some other symbol). In those cases, write Java code that means the same thing. For
example, to express the square root of three, write, MATH.sqrt(3), because √3 may not
render correctly.
|