Adding the Spring Style Guide (#7)
* Adding the Spring Style Guide Per a request from Michael Minella, I'm adding the Spring Style Guide to spring-doc-resources, giving it a more sensible location than my personal account. * Updated style guide I know more about Asciidoctor than I did when I last modified the style guide, so I set up better Asciidoctor attributes. I also trimmed off a bit at the end.
This commit is contained in:
parent
ec67c149ff
commit
8c2f3ae62d
|
@ -0,0 +1,545 @@
|
|||
[[spring-style-guide]]
|
||||
= Spring Style Guide
|
||||
:icons: font
|
||||
:toc: left
|
||||
:toc-levels: 4
|
||||
:docinfo: shared
|
||||
:sectanchors:
|
||||
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
http://asciidoctor.org/docs/user-manual/[Asciidoc User Manual].
|
||||
|
||||
This style guide covers the following topics:
|
||||
|
||||
* <<spring-style-guide-goal-audience>>
|
||||
* <<spring-style-guide-titles>>
|
||||
* <<spring-style-guide-headings>>
|
||||
* <<spring-style-guide-lists>>
|
||||
* <<spring-style-guide-tables>>
|
||||
* <<spring-style-guide-source-code-listings>>
|
||||
* <<spring-style-guide-links>>
|
||||
* <<spring-style-guide-images>>
|
||||
* <<spring-style-guide-admonitions>>
|
||||
* <<spring-style-guide-maintaining-flow>>
|
||||
* <<spring-style-guide-writing-sentences>>
|
||||
* <<spring-style-guide-wording>>
|
||||
* <<spring-style-guide-content-toggling>>
|
||||
|
||||
[[spring-style-guide-goal-audience]]
|
||||
== The Goal and the Audience
|
||||
|
||||
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.
|
||||
|
||||
[[spring-style-guide-titles]]
|
||||
== Titles and Subtitles
|
||||
|
||||
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 <<spring-style-guide-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.
|
||||
|
||||
[[spring-style-guide-headings]]
|
||||
== Headings
|
||||
|
||||
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).
|
||||
|
||||
[[spring-style-guide-lists]]
|
||||
== Lists
|
||||
|
||||
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 <<spring-style-guide-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
|
||||
<<spring-style-guide-highlighting>>.
|
||||
|
||||
[[spring-style-guide-tables]]
|
||||
== Tables
|
||||
|
||||
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):
|
||||
|
||||
.Colors
|
||||
[options="header"]
|
||||
|=====
|
||||
|Color|Red|Blue|Yellow
|
||||
|Green||*|*
|
||||
|Purple|*|*|
|
||||
|Orange|*||*
|
||||
|=====
|
||||
|
||||
In Spring's documentation, we do not number tables.
|
||||
|
||||
[[spring-style-guide-source-code-listings]]
|
||||
== Source Code Listings
|
||||
|
||||
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.
|
||||
|
||||
[[spring-style-guide-links]]
|
||||
== Links and Anchors
|
||||
|
||||
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 <<spring-style-guide-wording>> for another example.
|
||||
|
||||
[[spring-style-guide-images]]
|
||||
== Images
|
||||
|
||||
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.
|
||||
|
||||
[[spring-style-guide-admonitions]]
|
||||
== Admonitions
|
||||
|
||||
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
|
||||
|
||||
[[spring-style-guide-maintaining-flow]]
|
||||
== Maintaining the Flow
|
||||
|
||||
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.
|
||||
|
||||
[[spring-style-guide-writing-sentences]]
|
||||
== Writing Sentences
|
||||
|
||||
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.
|
||||
|
||||
[[spring-style-guide-wording]]
|
||||
== Wording
|
||||
|
||||
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
|
||||
<<spring-style-guide-words-avoid>> 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-style-guide-spelling>>
|
||||
* <<spring-style-guide-highlighting>>
|
||||
* <<spring-style-guide-words-avoid>>
|
||||
* <<spring-style-guide-writing-numbers>>
|
||||
|
||||
|
||||
[[spring-style-guide-spelling]]
|
||||
=== Spelling
|
||||
|
||||
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.
|
||||
|
||||
|
||||
[[spring-style-guide-highlighting]]
|
||||
=== Highlighting
|
||||
|
||||
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
|
||||
<<spring-style-guide-source-code-listings>>.
|
||||
|
||||
|
||||
[[spring-style-guide-words-avoid]]
|
||||
=== Words to Avoid or Avoid Misusuing
|
||||
|
||||
"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,cache2` than as
|
||||
`foo,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?
|
||||
|
||||
[[spring-style-guide-writing-numbers]]
|
||||
=== Writing Numbers
|
||||
|
||||
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.
|
||||
|
||||
[[spring-style-guide-content-toggling]]
|
||||
== Content Toggling
|
||||
|
||||
Some Spring documents include competing sets of content. The primary example of this
|
||||
kind of content is XML configuration versus Java-based (annotation-driven) configuration.
|
||||
In those cases, you can add a set of toggles to the top of the document.
|
||||
|
||||
When you use content toggling, remember to make each content set make sense both on its
|
||||
own and in the presence of the rest of the document. Also, if you include the option to
|
||||
have all the content sets available at once, remember to write all the content so that it
|
||||
makes sense both together and when a particular set of content has been chosen.
|
Loading…
Reference in New Issue