Embed Size (px)
Citation preview
Document Design PrinciplesNo matter what the output is, there are generally four basic principles of document design:
1. Grouping & Separation (also called Proximity)2. Alignment 3. Contrast4. Repetition
Document Design PrinciplesAlong with the four basic principles, there are several that are useful for online technical documents:
1. Chunking2. Callouts3. Code blocks
Document Design PrinciplesYou 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
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.
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
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.
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 VendorCommercial 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.
Alignment • Focuses attention to specific elements on the page• Good examples are lists, bulleted and numbered lists, and
indentation
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.
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 hereState/Province - this is your state, province, or administrative unit.City - this is your city, town, or locality.
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.
Contrast• Used to highlight certain elements on the page • Good examples are bolding, italics, and (limited) color
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 hereState/Province - this is your state, province, or administrative unit.City - this is your city, town, or locality.
Contrast and AlignmentContrast 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.
Repetition• Used to keep the document consistent in style • Good examples are using headings and font choices
consistently throughout the document
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
Repetition (continued)
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
Repetition (continued)
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!
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
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..
Style GuideNo 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)
Word ListFor 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.
Chunking • Breaking up your text into smaller, more easily read pieces
(chunks) • Chunking can be used with almost any type of writing
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.
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.
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.
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.
Callouts (continued)
Code BlocksCode 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 Block2. Directly on the page: type in a left curly brace and the word
code: {code
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.
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.
Any questions….? I’ll be glad to answer any questions now or in the future.
• You can contact me at: [email protected]• My website: http://alanbowman.net
Thank you for your time.
