The document discusses basic principles of document design including grouping and separation, alignment, contrast, and repetition. It provides examples of how these principles can be applied when formatting text, lists, headings, and other elements. The document also discusses additional principles for online technical documents such as chunking text, using callouts, and code blocks to highlight examples.

1. Document Design:
Basic Principles
Presentation by: Alan Bowman
alanbowman.net

2. Document Design Principles
No matter what the output is, there are generally four basic
principles of document design:
1. Grouping & Separation (also called Proximity)
2. Alignment
3. Contrast
4. Repetition

3. Document Design Principles
Along with the four basic principles, there are several that are
useful for online technical documents:
1. Chunking
2. Callouts
3. Code blocks

4. Document Design Principles
You can use these principles to improve your documents:
• In Confluence Pages
• In JIRA comments
• On your website
• In support tickets
• In Git or SVN commit messages
• Anywhere you have to produce output for someone to read

5. Document Design Principles
• These principles exist for one reason – to make it easier for
someone to read what you’ve written.
• They won’t make you a better writer
• They won’t improve your grammar
• They won’t fix any mistakes in your writing
They’ll just make it easier to read.

6. Grouping & Separation
• Group similar things together
• Separate things that are not similar
• Good examples are grouping similar items together in one
section, and separating other items in a different section

7. Grouping & Separation (cont.)
Hosting Co. sells commercial SSL certificates from GlobalSign
and AlphaSSL. Please contact Hosting Co. Sales for more
information about the SSL certificates available.
Commercial SSL certificates are also available from many
different third party vendors and at many different price points.
If you purchase your SSL certificate through a third party
provider, you will be responsible for ordering, installing,
renewing, and maintaining your SSL certificate.
If you need assistance from Hosting Co. to order or install your
third party SSL certificate that will be considered a billable
service.

8. Grouping & Separation (cont)
Purchasing an SSL Certificate from Hosting Co.
Hosting Co. sells commercial SSL certificates from GlobalSign and AlphaSSL. More information
about the commercial SSL certificates sold by Hosting Co. can be found here – Hosting Co. SSL
Certificates.
Hosting Co. offers a wide range of SSL certificates, from a low-cost SSL certificate all the way
up to an Extended Validation certificate that shows the green bar in the latest browsers. Please
contact Hosting Co. Sales for more information about the SSL certificates available.
Purchasing an SSL Certificate from a Third Party Vendor
Commercial SSL certificates are also available from many different third party vendors and at
many different price points. If you purchase your SSL certificate through a third party provider,
you will be responsible for ordering, installing, renewing, and maintaining your SSL certificate.
If you need assistance from Hosting Co. to order or install your third party SSL certificate that
will be considered a billable service.

9. Alignment
• Focuses attention to specific elements on the page
• Good examples are lists, bulleted and numbered lists, and
indentation

10. Alignment (continued)
Name - this is a name to help you identify the SSL certificate,
this is NOT the domain name being used by the SSL certificate.
Certificate type - this should be set to self-signed. Key length -
leave this at 2048 unless you have a very specific reason to
change it. 2 Letter country code - you can find your two letter
country code here State/Province - this is your state, province,
or administrative unit. City - this is your city, town, or locality.

11. Alignment (continued)
Name - this is a name to help you identify the SSL certificate,
this is NOT the domain name being used by the SSL certificate.
Certificate type - this should be set to self-signed.
Key length - leave this at 2048 unless you have a very specific
reason to change it.
2 Letter country code - you can find your two letter country
code here
State/Province - this is your state, province, or administrative
unit.
City - this is your city, town, or locality.

12. Alignment (continued)
• Name - this is a name to help you identify the SSL certificate,
this is NOT the domain name being used by the SSL certificate.
• Certificate type - this should be set to self-signed.
• Key length - leave this at 2048 unless you have a very specific
reason to change it.
• 2 Letter country code - you can find your two letter country
code here
• State/Province - this is your state, province, or administrative
unit.
• City - this is your city, town, or locality.

13. Contrast
• Used to highlight certain elements on the page
• Good examples are bolding, italics, and (limited) color

14. Contrast (continued)
Using the previous example, here is how contrast can be used to
highlight certain elements in the text:
Name - this is a name to help you identify the SSL certificate, this is
NOT the domain name being used by the SSL certificate.
Certificate type - this should be set to self-signed.
Key length - leave this at 2048 unless you have a very specific reason
to change it.
2 Letter country code - you can find your two letter country code here
State/Province - this is your state, province, or administrative unit.
City - this is your city, town, or locality.

15. Contrast and Alignment
Contrast and alignment are often used together:
• Name - this is a name to help you identify the SSL certificate, this is
NOT the domain name being used by the SSL certificate.
• Certificate type - this should be set to self-signed.
• Key length - leave this at 2048 unless you have a very specific reason
to change it.
• 2 Letter country code - you can find your two letter country code
here
• State/Province - this is your state, province, or administrative unit.
• City - this is your city, town, or locality.

16. Repetition
• Used to keep the document consistent in style
• Good examples are using headings and font choices
consistently throughout the document

17. Repetition (continued)
Headings:
• Each document has one Heading 1 as the document (not the
Page) title
• Heading 2 is for main sections
• Heading 3 for sub-sections
• Confluence has six heading choices

18. Repetition (continued)

19. Repetition (continued)
This makes the document hierarchy easy to understand, and
allows you to use the built-in Confluence Table of Contents
macro: Insert > Table of Contents

20. Repetition (continued)

21. Repetition (continued)
Use consistent wording to eliminate confusion:
• JBoss – the name of the application
• jboss – the name of the service
• E-mail (or email) – be consistent throughout the document
• Hosting Co. (never Hosting co or Hosting Company)
Look for any industry or company specific words and use them
consistently!

22. Repetition (continued)
Use consistent fonts and styling to eliminate confusion:
• Linux commands – service jboss7 restart
• Menu navigation – Insert > Table of Contents
• URLs – http://example.com
• Command names – cat, cd, vim

23. A quick aside…
I use a Style Guide and a Word List to maintain consistency in my
documentation.
• Style guide – what fonts and styling to use for certain types of
text, like the monospace bold italic for Linux
commands.
• Word List – a list of commonly used words specific to my
company and industry, like e-mail, website, Liferay-Portal-
Tomcat, WildFly, etc..

24. Style Guide
No need to reinvent the wheel – pick one of the existing style
guides and stick with it!
• Microsoft Manual of Style (4th edition)
• The IBM Style Guide
• Read Me First! A Style Guide for the Computer Industry (Sun)
• O’Reilly Stylesheet and Word List (online only)

25. Word List
For the word list you may need to reinvent the wheel a little bit.
• Look at corporate branding information
• Industry journals or trade publications or websites
• Use vendor or service names correctly
Be careful to get this right, especially if you’re in a regulated
industry where some words have specific legal meanings.

26. Chunking
• Breaking up your text into smaller, more easily read pieces
(chunks)
• Chunking can be used with almost any type of writing

27. Chunking (continued)
Hosting Co. sells commercial SSL certificates from GlobalSign and
AlphaSSL. If you purchase an SSL certificate from Hosting Co., we will
order and install the SSL certificate for you. However, you will be
required to answer some questions to start the order process, and
possibly reply to e-mails from the Certificate Authority as they try to
verify your business details. To begin the process, log in to the
Customer Portal at http://portal.hosting-co.com. Once you are logged
in, click on the Store link at the top right of the screen, and then on SSL
Certificates. This will show a listing of all the SSL Certificates offered by
Hosting Co.. Click on the name of an SSL Certificate to show a
description of the Cert, as well as the yearly price. If you are looking
for an Extended Validation SSL Certificate, Hosting Co. offers two - one
from GlobalSign and one from VeriSign.

28. Chunking (continued)
Hosting Co. sells commercial SSL certificates from GlobalSign and AlphaSSL. If you purchase an
SSL certificate from Hosting Co., we will order and install the SSL certificate for you.
However, you will be required to answer some questions to start the order process, and
possibly reply to e-mails from the Certificate Authority as they try to verify your business
details.
To begin the process, log in to the Customer Portal at http://portal.hosting-co.com.
Once you are logged in, click on the Store link at the top right of the screen, and then on SSL
Certificates. This will show a listing of all the SSL Certificates offered by Hosting Co.. Click on
the name of an SSL Certificate to show a description of the Cert, as well as the yearly price.
If you are looking for an Extended Validation SSL Certificate, Hosting Co. offers two - one from
GlobalSign and one from VeriSign.

29. Callouts and Code Blocks
• Callouts are used to draw attention to Notes, Tips, Info, and
Warnings in the text
• Code Blocks are used to highlight source code examples or
command line examples in the text
These examples are Confluence specific, but most WYSIWYG
editors will have something similar, and you can do the same
thing using inline HTML styles or CSS.

30. Callouts
• Confluence has four types of callouts: Warning, Note, Info,
and Tip
• Two ways to insert them in Confluence – from the Insert
menu or directly on the page.
1. Insert menu: Insert > Other macros > Formatting (select the
callout from the list presented)
2. Directly on the page: type in a left curly brace { and the first
letters of the callout, like {war - Confluence will auto-populate
the rest.

31. Callouts (continued)

32. Code Blocks
Code blocks are used to highlight source code or command line
examples.
• Two ways to insert them in Confluence – from the Insert
menu or directly on the page.
1. Insert menu: Insert > Other macros > Formatting > Code Block
2. Directly on the page: type in a left curly brace and the word
code: {code

33. Code Blocks (continued)
In the Page Edit function, you can set the Syntax highlighting of
the code block – click on the title bar of the code block, and
then on Edit. There will be a Syntax highlighting drop-down,
along with options to set the Title and Theme.

34. More information…
Books on document design:
• The Non-Designer’s Design Book, 3rd Edition – Robin Williams
(Peachpit Press)
• Developing Quality Technical Information, 2nd Edition –
Hargis, Carey, Hernandez, Hughes, Longo, Rouiller, Wilde (IBM
Press)
• Some academic style guides like MLA, AP, CMS, etc.

35. Any questions….?
I’ll be glad to answer any questions now or in the future.
• You can contact me at: alanbowman@gmail.com
• My website: http://alanbowman.net
Thank you for your time.