/
spring-style-guide.html
976 lines (976 loc) · 38.3 KB
/
spring-style-guide.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="Asciidoctor 1.5.5">
<title>Spring Style Guide</title>
<link rel="stylesheet" href="./style-guide-stylesheet.css">
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.6.3/css/font-awesome.min.css">
</head>
<body id="spring-style-guide" class="article">
<div id="header">
<h1>Spring Style Guide</h1>
</div>
<div id="content">
<div id="preamble">
<div class="sectionbody">
<div class="paragraph">
<p>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.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
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 <a href="style-guide-stylesheet.css">associated CSS file</a> defines the layout
details.
</td>
</tr>
</table>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
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
<a href="http://asciidoctor.org/docs/user-manual/">Asciidoc User Manual</a>.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>This style guide covers the following topics:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><a href="#spring-style-guide-goal-audience">The Goal and the Audience</a></p>
</li>
<li>
<p><a href="#spring-style-guide-titles">Titles and Subtitles</a></p>
</li>
<li>
<p><a href="#spring-style-guide-headings">Headings</a></p>
</li>
<li>
<p><a href="#spring-style-guide-lists">Lists</a></p>
</li>
<li>
<p><a href="#spring-style-guide-tables">Tables</a></p>
</li>
<li>
<p><a href="#spring-style-guide-source-code-listings">Source Code Listings</a></p>
</li>
<li>
<p><a href="#spring-style-guide-links">Links and Anchors</a></p>
</li>
<li>
<p><a href="#spring-style-guide-images">Images</a></p>
</li>
<li>
<p><a href="#spring-style-guide-admonitions">Admonitions</a></p>
</li>
<li>
<p><a href="#spring-style-guide-maintaining-flow">Maintaining the Flow</a></p>
</li>
<li>
<p><a href="#spring-style-guide-writing-sentences">Writing Sentences</a></p>
</li>
<li>
<p><a href="#spring-style-guide-wording">Wording</a></p>
</li>
</ul>
</div>
</div>
</div>
<div class="sect1">
<h2 id="spring-style-guide-goal-audience">The Goal and the Audience</h2>
<div class="sectionbody">
<div class="paragraph">
<p>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.</p>
</div>
<div class="paragraph">
<p>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.</p>
</div>
<div class="paragraph">
<p>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.</p>
</div>
<div class="paragraph">
<p>Above all, remember that the goal is to help people from all kinds of backgrounds learn to
use Spring.</p>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
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.
</td>
</tr>
</table>
</div>
</div>
</div>
<div class="sect1">
<h2 id="spring-style-guide-titles">Titles and Subtitles</h2>
<div class="sectionbody">
<div class="paragraph">
<p>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.</p>
</div>
<div class="paragraph">
<p>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).</p>
</div>
<div class="paragraph">
<p>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 <a href="#spring-style-guide-source-code-listings">Source Code Listings</a>.)</p>
</div>
<div class="paragraph">
<p>Spring technical documents do not use subtitles.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
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.
</td>
</tr>
</table>
</div>
</div>
</div>
<div class="sect1">
<h2 id="spring-style-guide-headings">Headings</h2>
<div class="sectionbody">
<div class="paragraph">
<p>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.</p>
</div>
<div class="paragraph">
<p>The Spring documentation uses the various heading levels as follows:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Heading level 1: Indicates a major chunk within a document. Each one should be an
important topic in its own right.</p>
</li>
<li>
<p>Heading level 2: Deals with something significant within a broader concept (which should
be the level-1 heading above the level-2 heading).</p>
</li>
<li>
<p>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.</p>
</li>
<li>
<p>Heading level 4: Deals with a meaningful detail in a larger document. This level should
be avoided in small documents.</p>
</li>
<li>
<p>Heading level 5: Should be avoided. May deal with a minor detail in a large document.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>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.</p>
</div>
<div class="paragraph">
<p>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.</p>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
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.)
</td>
</tr>
</table>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
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.
</td>
</tr>
</table>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
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).
</td>
</tr>
</table>
</div>
</div>
</div>
<div class="sect1">
<h2 id="spring-style-guide-lists">Lists</h2>
<div class="sectionbody">
<div class="paragraph">
<p>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.</p>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
Each list should have a lead paragraph (a paragraph that introduces the list,
often by describing the connection between its items).
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>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:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Green: Blue and yellow.</p>
</li>
<li>
<p>Purple: Red and blue.</p>
</li>
<li>
<p>Orange: Red and yellow.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>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 <a href="#spring-style-guide-source-code-listings">Source Code Listings</a>.)</p>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
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.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>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.</p>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
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.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>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.)</p>
</div>
<div class="paragraph">
<p>Ordinary lists rarely get titles or their own headings. However, instructions often get
headings.</p>
</div>
<div class="paragraph">
<p>As a rule, you should avoid using bold or italics in lists. See
<a href="#spring-style-guide-highlighting">Highlighting</a>.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="spring-style-guide-tables">Tables</h2>
<div class="sectionbody">
<div class="paragraph">
<p>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.</p>
</div>
<div class="paragraph">
<p>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.</p>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
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.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>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.</p>
</div>
<div class="paragraph">
<p>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.</p>
</div>
<div class="paragraph">
<p>The following example shows a sparse table that defines complementary colors (the items)
in terms of primary colors (the attributes):</p>
</div>
<table class="tableblock frame-all grid-all spread">
<caption class="title">Colors</caption>
<colgroup>
<col style="width: 25%;">
<col style="width: 25%;">
<col style="width: 25%;">
<col style="width: 25%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Color</th>
<th class="tableblock halign-left valign-top">Red</th>
<th class="tableblock halign-left valign-top">Blue</th>
<th class="tableblock halign-left valign-top">Yellow</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Green</p></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">*</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">*</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Purple</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">*</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">*</p></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Orange</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">*</p></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">*</p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>In Spring’s documentation, we do not number tables.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="spring-style-guide-source-code-listings">Source Code Listings</h2>
<div class="sectionbody">
<div class="paragraph">
<p>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.</p>
</div>
<div class="paragraph">
<p>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 description. 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. Also, 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.</p>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
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 <code>Item</code>
objects, it would be an error to write " <code>Items</code> " or " <code>Item</code> s ". Instead, you should
write " <code>Item</code> 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.
</td>
</tr>
</table>
</div>
</div>
</div>
<div class="sect1">
<h2 id="spring-style-guide-links">Links and Anchors</h2>
<div class="sectionbody">
<div class="paragraph">
<p>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.</p>
</div>
<div class="paragraph">
<p>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.</p>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
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 <a href="#spring-style-guide-wording">Wording</a> for another example.
</td>
</tr>
</table>
</div>
</div>
</div>
<div class="sect1">
<h2 id="spring-style-guide-images">Images</h2>
<div class="sectionbody">
<div class="paragraph">
<p>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.</p>
</div>
<div class="paragraph">
<p>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.</p>
</div>
<div class="paragraph">
<p>In Spring’s documentation, we do not number images.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="spring-style-guide-admonitions">Admonitions</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Admonitions offer a way to provide special knowledge to the reader. Admonitions come in
five varieties:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Note admonitions: Offer additional information that the reader may find helpful but that
is not crucial to the content.</p>
</li>
<li>
<p>Important admonitions: Call out things that the reader really should know when working
with the content.</p>
</li>
<li>
<p>Tip admonitions: Offer shortcuts or other details that make things easier or faster for
the reader.</p>
</li>
<li>
<p>Caution admonitions: Let readers know of common errors or other issues that may slow
their work or send them down an unproductive path.</p>
</li>
<li>
<p>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).</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The rest of this section contains sample admonitions, to show the admonition icons.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
Sample note admonition
</td>
</tr>
</table>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
Sample tip admonition
</td>
</tr>
</table>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
Sample important admonition
</td>
</tr>
</table>
</div>
<div class="admonitionblock caution">
<table>
<tr>
<td class="icon">
<i class="fa icon-caution" title="Caution"></i>
</td>
<td class="content">
Sample caution admonition
</td>
</tr>
</table>
</div>
<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
<i class="fa icon-warning" title="Warning"></i>
</td>
<td class="content">
Sample warning admonition
</td>
</tr>
</table>
</div>
</div>
</div>
<div class="sect1">
<h2 id="spring-style-guide-maintaining-flow">Maintaining the Flow</h2>
<div class="sectionbody">
<div class="paragraph">
<p>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.</p>
</div>
<div class="paragraph">
<p>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."</p>
</div>
<div class="paragraph">
<p>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.</p>
</div>
<div class="paragraph">
<p>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.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="spring-style-guide-writing-sentences">Writing Sentences</h2>
<div class="sectionbody">
<div class="paragraph">
<p>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.</p>
</div>
<div class="paragraph">
<p>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.</p>
</div>
<div class="paragraph">
<p>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.</p>
</div>
<div class="paragraph">
<p>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.</p>
</div>
<div class="paragraph">
<p>Except when serving as separators 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:".</p>
</div>
<div class="paragraph">
<p>Put conditional phrases first. Consider the following sentence: "You can use the <code>new</code>
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 <code>new</code> keyword."</p>
</div>
<div class="paragraph">
<p>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.</p>
</div>
<div class="paragraph">
<p>In short, keep the writing simple. By doing so, you make things better for Spring’s
readers.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="spring-style-guide-wording">Wording</h2>
<div class="sectionbody">
<div class="paragraph">
<p>"Never use a fifty-cent word when a five-cent word will do." In other words, prefer simple
words to more complex words and shorter words to longer words.</p>
</div>
<div class="paragraph">
<p>In addition to that fundamental advice, this section also covers the following topics:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><a href="#spring-style-guide-spelling">Spelling</a></p>
</li>
<li>
<p><a href="#spring-style-guide-highlighting">Highlighting</a></p>
</li>
<li>
<p><a href="#spring-style-guide-words-avoid">Words to Avoid or Avoid Misusuing</a></p>
</li>
<li>
<p><a href="#spring-style-guide-writing-numbers">Writing Numbers</a></p>
</li>
</ul>
</div>
<div class="sect2">
<h3 id="spring-style-guide-spelling">Spelling</h3>
<div class="paragraph">
<p>Spring’s documentation standard uses American spelling, including the following details:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Words ending in "or" (such as "behavior") do not have a "u" between the "o" and the "r".</p>
</li>
<li>
<p>"Magic" does not have a "k".</p>
</li>
<li>
<p>Words ending in "ise" and "isation" (such as "specialise" and "specialisation") end in
"ize" and "ization", respectively ("specialize" and "specialization").</p>
</li>
<li>
<p>And so on.</p>
</li>
</ul>
</div>
</div>
<div class="sect2">
<h3 id="spring-style-guide-highlighting">Highlighting</h3>
<div class="paragraph">
<p>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.</p>
</div>
<div class="paragraph">
<p>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.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
Code within sentences should be highlighted by using the code font. See
<a href="#spring-style-guide-source-code-listings">Source Code Listings</a>.
</td>
</tr>
</table>
</div>
</div>
<div class="sect2">
<h3 id="spring-style-guide-words-avoid">Words to Avoid or Avoid Misusuing</h3>
<div class="dlist">
<dl>
<dt class="hdlist1">"foo" and "bar"</dt>
<dd>
<p>"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 <code>cache1,cache2</code> than as
<code>foo,bar</code>. 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.</p>
</dd>
<dt class="hdlist1">"terminate"</dt>
<dd>
<p>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.</p>
</dd>
<dt class="hdlist1">"execute"</dt>
<dd>
<p>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.</p>
</dd>
<dt class="hdlist1">"abort"</dt>
<dd>
<p>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.</p>
</dd>
</dl>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
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.
</td>
</tr>
</table>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">"then"</dt>
<dd>
<p>"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."</p>
</dd>
<dt class="hdlist1">"if…​then…​"</dt>
<dd>
<p>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."</p>
</dd>
<dt class="hdlist1">"will" and the future tense</dt>
<dd>
<p>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.</p>
</dd>
<dt class="hdlist1">"above" and "below"</dt>
<dd>
<p>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."</p>
</dd>
<dt class="hdlist1">"just"</dt>
<dd>
<p>In many cases, you can remove "just" from a sentence without changing its
meaning. In those cases, you should remove it.</p>
</dd>
<dt class="hdlist1">"very"</dt>
<dd>
<p>"Very" can nearly always be removed without changing the meaning of the sentence.
In those cases, you should remove it.</p>
</dd>
<dt class="hdlist1">"simply", "easily", "obviously", and so on</dt>
<dd>
<p>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?</p>
</dd>
</dl>
</div>
</div>
<div class="sect2">
<h3 id="spring-style-guide-writing-numbers">Writing Numbers</h3>
<div class="paragraph">
<p>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 write it 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:
<code>zero</code>, <code>one</code>, <code>two</code>, <code>ten</code>, <code>11</code>, <code>12</code>, <code>20</code>, <code>30</code>, <code>-0</code>, <code>-1</code>, <code>-2</code>, <code>-10</code>, <code>-20</code>,
<code>0.0</code>, <code>0.1</code>, <code>1.0</code>, <code>-1.0</code>, <code>2.3</code>, <code>-2.3</code>, <code>i</code>, <code>-i</code>, <code>-2i</code>, <code>e</code>, <code>-e</code>, and <code>-2e</code>.</p>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
Avoid using symbols that are more complex than a single letter in the English
alphabet (such as <code>i</code> and <code>e</code>). 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, <code>MATH.sqrt(3)</code>, because <code>√3</code> may not
render correctly.
</td>
</tr>
</table>
</div>
</div>
</div>
</div>
</div>
<div id="footer">
<div id="footer-text">
Last updated 2017-11-21 12:30:52 CST
</div>
</div>
</body>
</html>