technical documentation style guide - … documentation style guide i ... cascading style sheet ......

Technical Documentation Style Guide

SmartPipes, Inc

Technical Documentation Style Guide SmartPipes, Inc. 565 Metro Place South, Suite 300Dublin, OH 43017Updated 6/12/2003

Copyright © 2003 SmartPipes, Inc. All rights reserved. SmartPipes and the SmartPipes logo are registered service marks of SmartPipes, Inc. Cisco is a trademark of Cisco Systems Inc. Windows is a trademark of Microsoft Corporation. All other brand names or product names mentioned in this document are trademarked by their respective owners.

No part of this document, including interior design and cover design may be reproduced or transmitted in any form, by any means (electronic, photocopying, or otherwise) without the prior written permission of SmartPipes, Inc.

Table of ContentsTechnical Documentation Style Guide

i

Table of ContentsAbout This Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Audience. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Knowledge Level of Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Styles for All Technical Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2AAA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2base configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2beside . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2bold – (black) (6/12/03) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3bulleted lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4capitalization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4Cisco IOS device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4Cisco PIX firewall device. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4check box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4choose one of the following (6/2/03) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4clear. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5click . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5click one of the following option buttons (updated 6/2/03) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5co-branded partner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5conditional text (updated 6/2/03) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5customer service or Customer Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5deploy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5dialog (6/2/03) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6do one of the following (6/2/03) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6download . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6dynamic text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6e-mail. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6enterprise administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7“enterprises who” vs. “enterprises that” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7go to (for procedural information) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7go to (next step) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7home page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8hub and spoke . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8important . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8internet service provider (ISP) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8introductory sentences/stem sentences (6/2/03) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9link. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9list box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9log on and logon vs. log in and login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

SmartPipes, Inc.


ii

log on to, log off. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9manually apply . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9NetScreen device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9network administrator vs. service administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10next to . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10note (6/2/03) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10option button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10page. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10page elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10plural form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11preferred terms (see terminology) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11references. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11SAI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11select. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12selection box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Service Administration Interface (SAI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12service administrator vs. network administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12SmartPipes information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12solution provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13stages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Start menu location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14stem sentences/introductory sentences (6/2/03) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14steps, multiple (6/2/03 - removed the table option) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14terminology (6/2/03 added terms plus alpha sorted) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14upload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15warning (6/12/03) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Online Help Styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17branding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17browse sequence. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18cascading style sheet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18cross-references (6/2/03). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18delete topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18faqs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18fields and descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18fields and procedures in tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19graphics in the UI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19headings and subheadings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19help topic guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20links. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21menu bar. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21numbered lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21popups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

SmartPipes, Inc.


iii

procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21procedures within procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22related topics buttons (6/2/03 - removed EULA) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22required fields (6/2/03). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22RoboHelp default settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22spacing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23standard online Help sections (6/2/03) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23starting procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23table of contents (TOC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24UI naming conventions and usage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Appendix A: Help-to-PDF Process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Help-to-PDF Process (3/14/2003) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Help-to-MS Word Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Importing MS Word Documents-to-FrameMaker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31Format the FrameMaker Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Converting MS Word Styles to FrameMaker Styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34Troubleshooting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35FrameMaker-to-PostScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37PostScript-to-PDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37Project Review . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Appendix B: FrameMaker Document Styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Appendix C: PDF Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Appendix D: Screen Capture Guidelines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49RoboHelp Screen Capture Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49FrameMaker Screen Capture Guidelines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Appendix E: Online Help Index Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Appendix F: Online Help Glossary Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Appendix G: Online Help Related Topic Button Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

Appendix H: User Interface Screen Text Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53updating screen text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

SmartPipes, Inc.

About This DocumentTechnical Documentation Style Guide

1

About This Document

This document provides the Technical Documentation department with style guidelines for all Technical Documentation projects. Styles include, but are not limited to fonts, sizes, format, and special word preferences.

Important: If there is a Tech. Doc. design document specific for the feature that provides style guides, the guidelines in the design document take precedence over those in this style guide and in the Microsoft Manual of Style for Technical Publications.

Important: When in doubt use www.webopedia.com or Microsoft Manual of Style for Technical Publications.

Audience

Enterprises and solution providers are the audience for all technical documentation. Solution providers can be service providers, VARS, Internet Service Providers (ISPs), or integrators.

Note: Customers of solution providers will be calling the customer service of the solution provider. If an enterprise buys SmartPipes software directly from us (ex. a franchise) vs. from a solution provider, the enterprise’s corporate customer service dept. will work with and call the SPTAC, if necessary.

Knowledge Level of Audience

This section describes the technical documentation audience:

• Expert Audience – The audience knowledge level that we can target for most documentation is the Network Operations Center (NOC) engineer. Experts may also find a need for documentation to familiarize themselves with process flow and SmartPipes-specific terminology. Help systems, product descriptions, release notes, and feature announcements target this audience.

• Novice/Intermediate – This segment of the audience may include solution provider and enterprise sales prospects and individuals requiring high-level, less technical information about the SmartPipes product suite. Marketing and sales materials target this audience.

SmartPipes, Inc.

Styles for All Technical DocumentationTechnical Documentation Style Guide

2

Styles for All Technical Documentation

AAA

Use the article “a” rather than “an” with AAA. The audience we address in our documentation will understand that this term is pronounced “triple-A”, so “a” is the appropriate article to use.

Do not write out as “triple A” or any variation; use only AAA.

acronyms

Follow the standard practice of spelling out on first use and then using the acronym going forward. Use of acronyms is fine in headings.

Do not include definitions of acronyms in topics, except in the process documents.

For more information, see “SAI” on page 11.

administrator

Do not use the term service administrator, enterprise administrator, or administrator. In general follow these guidelines:

• If you are using the term to describe an administrator who is responsible for the administrative tasks in SAI or PAI, use SAI administrator or PAI administrator.

• If you are using the term to describe an administrator who uses our software (but, who isn’t responsible for the administrative tasks in PAI or SAI), use network administrator.

• If a document mixes both cases of SAI/PAI administrator and network administrator, use network administrator consistently within the document rather than mixing uses. (6/2/03)

area

More than one page of information in a site. For example, the Create a Customer Account area begins on the home page and contains multiple pages on creating a customer account.

base configuration

Use base configuration instead of base configuration file. Not using the word file because it is implied.

beside

Acceptable as long as it is consistent throughout the documentation. Also acceptable is next to as long as it is consistent throughout the documentation.

SmartPipes, Inc.


3

bold – (black) (6/12/03)

• Page names are never bolded.

Bold the following only when they are in a procedure:

• Button names

• Field names

• Exact text you type into fields

• Links

Note: Links are bolded in a procedure when the user is required to click on the link to complete the step in the procedure and the link is the exact name of the link.

Example: Click the Submit link to submit the feedback form.

• List box names

• List box choices

• Option button names

• Tab names

• Menus and menu options (example: Select Open from the File menu.)

• Icon names

Note: These items should be emphasized with bold lettering when they are objects of actions, in procedures. However, not all objects of actions should be emphasized. There may be a few excep-tions to this rule in SAI, such as tab names.

Example: Click the New Contact tab.

Example: The New Policy page, Interface tab displays.

• Bold all punctuation after a bolded word.

Example: Important: or Note:

Example: Click View the Audit Log.

Bold in Notes, Importants, Warnings:

• For Documents and Help: Certain words within Notes, Importants, and Warnings can be emphasized with bold lettering. They include words like no, not, never, must.

• For Screen Text: Following the style of the screen text. If the screen text is using bold for certain things in Notes, Importants, and Warnings, follow the established style.

bulleted lists

• Use for lists of information that are not sequential procedures or processes.

• Complete sentences: Begin with a capital letter and use a period. Each bullet in the list must be a complete sentence.

• Incomplete sentences: Begin with a capital letter and do not use a period.

• Be consistent when using complete or incomplete sentences (all complete or all incomplete).

• Use solid, black circle bullets that are set up in the templates.

SmartPipes, Inc.


4

• For definitions within a bulleted list use this format:

Incomplete: This option...

button

Use the term button after a button name.

Example: Click the Add button.

capitalization

• Follow MS style guidelines.

• Do not capitalize solution provider.

Cisco IOS device

Standard terminology for a Cisco IOS device throughout documentation. (Version 2.8) of the software removed the following terminology from the SAI and PAI Help “standard Cisco device” and replaced with Cisco IOS device.

First Use: Cisco IOS® device

Second Use: Cisco IOS device

Incorrect: Cisco IOS router, IOS router, IOS device, Cisco device, Cisco router.

Cisco PIX firewall device

Standard terminology for a Cisco PIX firewall device.

• First Use: Cisco PIX® firewall device

• Second Use: Cisco PIX firewall device

• Incorrect: Cisco PIX device, PIX device, PIX router

check box

• Use select when referring to the action of marking a check box. Do not use place a check in the box.

• Use the term shaded instead of grayed when referring to a read-only check box.

choose one of the following (6/2/03)

Do one of the following vs. choose one of the following vs. click one of the following option buttons: SAI and PAI Help use: Do one of the following.

SmartPipes, Inc.


5

clear

Use clear when referring to de-selecting check boxes. Select and clear are used for opposing actions on check boxes and selection boxes.

click

Use click when referring to mouse action. Use click instead of select for most procedural selection actions, unless referring to check boxes or selection boxes.

click one of the following option buttons (updated 6/2/03)

Do one of the following vs. choose one of the following vs. click one of the following option buttons. SAI and PAI Help use; Do one of the following.

co-branded partner

Do not use in any documentation. Change to solution provider or enterprise depending on the context.

conditional text (updated 6/2/03)

No documentation uses conditional text at this time.

customer service or Customer Services

In online Help, use customer service vs. customer support when referring to a generic customer service department, such as for multiple solution providers.

When referring to SmartPipes TAC, follow these guidelines:

• First reference: SmartPipes Software Technical Assistance Center (SPTAC)

• Subsequent references: SPTAC

deploy

To put into action. When a basic configuration is deployed to a device, it puts into action the commands in the base configuration, and the device responds accordingly.

SmartPipes, Inc.


6

dialog (6/2/03)

• Dialog box should be used when a dialog box contains information such as an Important, Warning, Caution or a question with a Yes, No, Cancel option. A dialog box will not allow the user to continue without responding to the dialog question.

• Window should be used when a window appears that contains multiple options for the user or the user can perform multiple tasks using the window.

Important: (Version 2.8) All topics that use “non-SAI” windows need to have the steps generalized rather than documenting the Windows platform windows. (Base Configuration downloads and uploads.)

Reason: All Windows platforms (XP, 2000, 98, 95) have a different sequence and different looking windows. The audience for the SmartPipes software will know how to upload and download files with generic instructions.

• Page: One Web page of information that includes the tabs (if applicable). Do not use Web page or window or screen. For additional information, see “page elements” on page 10.

Examples:

Browsing, selecting a file and clicking OK all in the same place - this is a window.

Do you really want to delete? Yes or No - this is a dialog box.

do one of the following (6/2/03)

Do one of the following vs. choose one of the following vs. click one of the following option buttons: SAI and PAI Help use; Do one of the following.

download

To transfer data from one computer to another or to copy a file from a network file server to a computer on the network.

dynamic text

Follow MS style.

Example: where x is the number of devices.

e-mail

Use lowercase and hyphenated e-mail. Do not use email or E-mail. This is the Microsoft style as well.

SmartPipes, Inc.


7

enterprise administrator





“enterprises who” vs. “enterprises that”

Use "enterprises that." Do not use “enterprises who.” Example: Enterprises that have remote users... (vs. Enterprises who have remote users....

examples

Two ways to show examples:

• Inline paragraph style using the term “for example.” Do not move this example to a new line. You may either place the “for example” in the middle of a sentence or begin a new sentence.

• New paragraph style, similar to Notes and Importants. Begin this style on a new line and use bold.

Example:

field

• Use in instead of on when referring to information typed in a field.

• Field vs. Text Box - Use field instead of text box.

go to (for procedural information)

For links to another procedure from within a procedural topic, use either Go to [topic title] or Go to [topic title] for procedural information.

go to (next step)

Use go to rather than “proceed to”. (6/2/03)

Avoid placing a step number in the procedure if it is the next step you are going to. If there are steps between the current step and the step you are going to, it is acceptable to place the step number in the procedure.

SmartPipes, Inc.


8

Examples:

5. Click the Next button to initiate the upload. Go to the next step. (Instead of Go to step 6.)

5. Do one of the following:

• If x, go to the next step.

• If y, go to step 10.

home page

Lowercase home page unless referring to an actual Web page name. Use the system name before the term home page.

Example: Click the home button to go to the SAI home page.

hub and spoke

Do not use the ampersand with hub and spoke. Hyphenate the term only when using it as an adjective.

Example: hub-and-spoke topology

important

• Importants contain need-to-know information that could affect system use.

• A note, warning, or reference should be black, bold, upper and lower case letters, followed by a colon. Associated note text should begin on the same line as the Note label (ex. Note: This ljdfldkf.) Ex. Note:

• Only the introductory word should be bolded, not the entire sentence.



internet service provider (ISP)

An Internet Service Provider is a company that sells Internet services to other companies.

A solution provider for SmartPipes can be an Internet Service Provider, but doesn’t have to be, so we refer to them generically as a solution provider. See “SmartPipes information” on page 12.

introductory sentences/stem sentences (6/2/03)

• Introductory sentences have been removed from SAI and PAI Help with the Version 2.8. Introductory sentences are no longer required to introduce procedures or tables in any documentation, online help, or PDF.

SmartPipes, Inc.


9

items

Do not use to refer to resources in SAI that the customer can manage, such as VPN templates, devices, service points, etc. - use resources instead. See “resources” on page 11.

link

Use link instead of hyperlink. When creating a link, do not include the punctuation following the link as part of the link.

list box

Use list box vs. drop-down list or selection box.

log on and logon vs. log in and login

Use log on as a noun and logon as an adjective. Follow this MS Style Guide usage when discussing anything in the general sense. If you are specifically discussing a field on the UI and it’s incorrect on the UI, match the UI.

log on to, log off

Use log on to to refer to connecting to a Web site, application, or network. Use log off to refer to disconnecting from a Web site, application, or network. Do not use log off of or log off from.

manually apply

When referring to “applying a base configuration via telnet or copy and paste,” use apply with the word manually. When you apply a base configuration to a device, it is done manually. This phrase only applies to newly activated devices.

Example: After downloading the base configuration, you must manually apply it to the device or you must manually apply it to the device.

NetScreen device

Standard terminology for a NetScreen device throughout documentation.

First Use: NetScreen® device

Second Use: NetScreen device

Incorrect: NetScreen appliance, NetScreen firewall appliance

SmartPipes, Inc.


10

network administrator vs. service administrator





next to

Acceptable as long as it is consistent throughout the documentation. Also acceptable is “beside” as long as it is consistent throughout the documentation.

note (6/2/03)

• Notes contain need-to-know supplementary information that will not affect system use.





option button

Use option button instead of radio button. Add the term button on the end for clarity in procedures only.

page

• One Web page of information that includes the tabs (if applicable). Do not use Web page or window or screen. For additional information, see “page elements” on page 10.

• In procedures, reference the page name over the tab name unless you clicked the actual tab.

page elements

When referring to Web page elements, the page is the highest level, section is a part of a page, and

SmartPipes, Inc.


11

field is an element on the page. If necessary, they should be used in the following order: area, page, tab, section, field. For more information, see “page” on page 10, “tab” on page 14, “section” on page 11, “field” on page 7.

plural form

Use the plural form, rather than singular form or (s), when potentially describing more than one person, place, or thing.

• Correct: The SAI administrators responsible for….

• Incorrect: The SAI administrator(s) responsible for….

preferred terms (see terminology)

references

• References can be either cross-references or additional resources. When referencing a linked topic, use the MS style. The reference is not used in online Help.



• Certain words within Notes, Importants, and Warnings can be emphasized with bold lettering. They include words like no, not, never, must.

resources

Use to refer to resources in SAI that the customer can manage, such as VPN templates, devices, service points, etc. Use this term when referring to a set of resources versus a single item; for example, Adding Resources to VPN Policies. When referring to a specific item in SAI, refer to that resource’s name; for example, service point, which replaces the term “items” in SAI.

SAI

Acronym for Service Administration Interface. Do not use a the in front of the acronym unless referring to a noun after the acronym, such as the SAI navigation tree.

section

A part of a page. For more information, see “page elements” on page 10.

SmartPipes, Inc.


12

select

Use select when referring to keyboard action or referring to check boxes or selection boxes. Use click for most other procedural selection actions.

selection box

Use selection box vs. check box for boxes that contain either an X (x) or a slash (/) in them. Use the verb select as you would for a check box.

Service Administration Interface (SAI)

Correct: Service Administration Interface

Incorrect: Service Administration Interface site

service administrator vs. network administrator





SmartPipes information

Use of the SmartPipes Name• When possible, do not refer to SmartPipes, the company name unless SmartPipes is in direct

reference to the SmartPipes product family or to specific SmartPipes products (Example: SmartPipes IP PolicyPro Authentication). When possible, keep company names generic. This keeps all solution provider changes to a minimum.

• Use customer service (lowercase singular) when in general referring to any customer service department. (specifically used for all end-customer documentation and in the online Help since these products may not refer to SPTAC department).

• When referring to SmartPipes customer service, follow these guidelines:

• First reference: SmartPipes Software Technical Assistance Center (SPTAC)

• Subsequent references: SPTAC

SmartPipes Product Family Naming Conventions/Guidelines

SmartPipes, Inc.


13

Naming Conventions

The product family platform name and the name of the individual products are:

• SmartPipes IP PolicyPro: the software platform itself; name of the product family

• SmartPipes IP PolicyPro SecureSite: our VPN/Site-to-site/Firewall/NAT management product

• SmartPipes IP PolicyPro Remote: our client software/remote policy management product

• SmartPipes IP PolicyPro Authentication: our hosted RADIUS/authentication policy management product

Usage Guidelines (updated 6/2/03)

• Use SmartPipes® IP PolicyPro followed by the name of the product on first reference.

Example (first reference): SmartPipes® IP PolicyPro SecureSite

• With all subsequent references use the name of the product.

Example (second reference): IP PolicyPro SecureSite

• The registered service mark (®) symbol only follows the word “SmartPipes” and is only used on the first reference.

Example (first reference): SmartPipes® IP PolicyPro SecureSite

Example (second reference): IP PolicyPro SecureSite

• The word “software” can be used after the product name for clarification purposes. If the word “software is used after the product name, it must be used consistently throughout the document.

Example: IP PolicyPro SecureSite software

• The term “SmartPipes software” can be used in a document to generically represent the SmartPipes product suite.

Use of the SmartPipes Name with the Possessive Case • Don't use the possessive ever. Yes, yes, we know it's confusing, but per Pam, Mark doesn't like us

to use it.

Example: SmartPipes Web-based interface (vs. SmartPipes’ Web-based interface.).

solution provider

A solution provider is a company that resells SmartPipes services. A solution provider can be an ISP, a service provider, VAR, or integrators. Do not capitalize solution provider unless it appears at the beginning of a sentence.

stages

Use Stages as a word to indicate the major components of a process, but only in the process topics that describe the process rather than in the detailed procedural topics. See GRE Process in SAI Help.

SmartPipes, Inc.


14

Start menu location

To indicate a path from the Windows Start menu, use arrows between each menu selection, as shown in the examples below. The arrow is located in the character map under the font Wingdings 3.

Example: Solution providers or third-party software developers can access the Client DPI Simulator from this path on the Start Menu: Start Programs SmartPipes Client Management Toolkit Tools

Client DPI Simulator.

Exception: When using Wordpad or Notepad, you cannot use the arrow from the character map. Instead, create an arrow using the dash and the greater than symbol, as shown in the example below.

Example: Solution providers or third-party software developers can access the Client DPI Simulator from this path on the Start Menu: Start -> Programs - > SmartPipes Client Management Toolkit - > Tools - > Client DPI Simulator.

stem sentences/introductory sentences (6/2/03)

• Introductory sentences have been removed from SAI and PAI Help with the Version 2.8. Introductory sentences are no longer required to introduce procedures or tables in any documentation help or PDF.

steps, multiple (6/2/03 - removed the table option)

• Use bullets for procedure steps with multiple steps.

Note: When you have two or fewer options with no jumping off steps, strongly suggest using bul-lets.

• When referring to steps in procedures, use lower case and no bold.

Example: Repeat steps 1 through step 3 for each... or Proceed to step 3.

tab

• Web page that has labeled tabs on it. For additional information, see “page elements” on page 10.

• In procedures, reference the page name over the tab name unless you clicked the actual tab.

terminology (6/2/03 added terms plus alpha sorted)

Consistent Use1. Terminology should be consistent throughout document.

2. Buttons, tabs, icons, links are labeled what they are.

Example: Create a Contact button or Name link.

3. Use the terms listed first as the preferred term instead of the term listed second.

• access vs. gain entry

SmartPipes, Inc.


15

• Cisco IOS device vs. Cisco IOS router, Cisco router (For more information, see “Cisco IOS device” on page 4.

• Cisco PIX firewall device vs. Cisco PIX device, Cisco PIX (For more information, see “Cisco PIX firewall device” on page 4.

• displays vs. appears

• enables vs. allows

• field vs. text box

• host/subnet service point vs. VPN service point

• ID vs. id

• inserts vs. places

• in vs. on (when referring to information typed in a field)

• link vs. hyperlink

• NetScreen device vs. NetScreen firewall appliance, NetScreen appliance (For more informa-tion, “next to” on page 10.

• PAI administrator or SAI administrator vs. user (to describe who’s using the system in a feature announcement)

• must vs. need to

• option button vs. radio button

• policies vs. IP services policies

• resources vs. items

• select vs. choose

• type vs. enter (in a field)

• use vs. utilize

• user vs. end user

• want vs. desire

upload

The opposite of download is to upload, which means to copy a file from your own computer to another computer or to a larger central “host.” For example, if you use a personal computer to log on to a network and you want to send files across the network, you must upload the files from your PC to the network.

warning (6/12/03)

• Warnings contain need-to-know information that could have a negative impact on system use.

• A warning should be black, bold, followed by an exclamation point and no colon. Ex. Warning!


SmartPipes, Inc.


16




window

Use window when referring to a window in a software product that is not Web-based. Do not use screen.

Important: (Version 2.8) All topics that use “non-SAI” windows need to have the steps generalized rather than documenting the Windows platform windows. (Base Configuration downloads and uploads.)

Reason: All Windows platforms (XP, 2000, 98, 95) have a different sequence and different looking windows. The audience for the SmartPipes software will know how to upload and download files with generic instructions.

Dialog box and Window - Dialog box should be used when a dialog box contains information such as an Important, Warning, Caution or a question with a Yes, No, Cancel option. Window should be used when a window appears that contains multiple options for the user or the user has multiple things that can be done using the window.

Examples:

Browsing, selecting a file and clicking OK all in the same place - this is a window.

Do you really want to delete? Yes or No - this is a dialog box.

SmartPipes, Inc.

Online Help StylesTechnical Documentation Style Guide

17

Online Help Styles

branding

We brand our help projects for SmartPipes only. The XO, Fiberlink, UUNET, and Qwest branding is in production. The style sheets are applied by the Tech. Doc. Mgr. as needed.

Important: Additional entries to the style sheet are “tablehead2” which is a color for a section heading (used for second level table headings), and “tablehead3” which is color used for third level table headings. The following three table heading levels may not need to be used in the SAI Help, but they are in the style sheet. “tablehead1” is still used for first level table headings.

RGB reference guideThis table describes RGB specifications for SmartPipes and associated solution providers. We will continue to add RGB specifications to this table as we add solution providers.

Company RGB Value When to use

SmartPipes SmartPipes Green: r=56 g=138b=34

Heading 1 elementsHeading 3

Table Green:Red 231 Green 248 Blue 226

Background color for Heading row of any table.

Fiberlink H1-H3:#cc6600

Heading 1, 2, and 3 elements

tablehead:#99ccff


Qwest H1-H3:#2e3f51


tablehead:#a0b5c5


WorldCom WorldCom Blue:#003265

Heading 1 elementsHeading 3

Table Orange:#ffcd6d


XO H1-H3: #cc3300


tablehead: #ffffcc


SmartPipes, Inc.


18

browse sequence

Browse sequences are not used in help.

cascading style sheet

• The default cascading style sheet (error.css) uses SmartPipes color conventions. Copy and paste this style sheet into your online Help system, and then apply the style sheet to each topic.

cross-references (6/2/03)

• No See or See also cross-references. Instead, use one of the following:

• Preferred: For more information, see link.

delete topics

There is no Trashcan in SAI or PAI. Do not create a generic deleting topic that applies to anything that you delete. The goal is to document the delete feature where it exists and indicate that when the “something” is deleted, it is deleted permanently from SAI/PAI.

faqs

Use bullets instead of numbers for FAQ lists.

fields and descriptions

For more information, see “fields and procedures in tables” on page 19.

• Put information on the page that is necessary to complete the page table or process. For example, tab names are only necessary to include if they contribute to the understanding of the page.

• When a fields and descriptions table mixes tabs, buttons, etc. use tab, button, or column as part of description for clarification purposes only. Never need to use the words field, check box, or option button.

• Text in the Description column should start with an action word rather than a complete sentence.

SmartPipes, Inc.


19

fields and procedures in tables

For more information, see “tables” on page 24.

Tables with Tabs and Sections (updated 6/2/03)• In tables, bold field names when they are bulleted, with a colon, and followed by a definition. See

the screen shot above for a sample.

• Tab names are to be capitalized in the fields and descriptions table headings. In all instances, subtab names and section names should follow the capitalization used on the UI.

• All descriptions should start with a verb.

• No stem sentence is necessary to introduce fields in the fields and descriptions column.

• SAI and PAI Help systems have fields and description tables on the Viewing and Modifying topics. Wizards include bulleted fields and descriptions within the wizard steps in the procedures.

Note: There are some exceptions to this rule. We have created specific topics to explain terminol-ogy such as Interface Types, Policy Types, etc.

• Wizard procedures should be documented as they are in the existing SAI Help. The entire procedure should be included on one page.

Important: Table layout has changed drastically with the Quantum Scientific (version 2.8) release of the software. For screen shots and explanation of new table layout, see the SAI Help Design Document for Quantum Scientific.

graphics in the UI

If graphics are used in the UI, they are integral to the procedure, and they do not have a standard approved name, such as check box or option button, they must be represented in the Help:

• Use the term icon or button with the graphic name, depending on what it most looks like.

• The graphic name should be capitalized and bold and the term button or icon should be lowercase and not bold.

• The actual graphic should follow the graphic name.

• Up Arrow and Down Arrow are acceptable names for the graphics they represent.

Example: Click the Up Arrow button to change the priority of the policies.

headings and subheadings

headingsNote: Colors change according to solution provider color and are controlled by the style sheet. The style sheet is installed using the Help MSI installation.

• Heading 1 – Arial, Bold, 14 pt, Green “Red 56, Green 138, Blue 255” Usage: Page or Topic Title

• Heading 2 – Arial, Bold 12 pt, Green (not currently being used)

SmartPipes, Inc.


20

• Heading 3 – Arial, Bold 10 pt, SmartPipes Green Usage: Subhead or pop-up window title

• Page (topic title) Heading = Heading 1

• Subheading = Heading 3

• Table Heading = Use subheading format

• Table Column Titles = Body Text Bold, normal style tag, left justified.

subheadings Note: Colors change according to solution provider color and are controlled by the style sheet. The style sheet is installed using the Help MSI installation.

• Use when more than one topic on a page (ex. Introduction and Procedure)

• Use the Heading 3 style

• When subheading introduces a table, follow with a stem sentence to introduce the topic, using this format: This table describes -------.

• Use SmartPipes green or solution provider color (same as Heading1)

• Standard subheading titles include:

• Fields and Descriptions

• Steps/Actions

• Introduction

• Procedure

Note: If information cannot fit into pre-defined subheadings, the writer can create the needed sub-heading. Also, if the information is information that could apply to most Help systems, seek approval of the Tech Doc Mgr.

• Subheadings depend on what follows - can be singular or plural

help topic guidelines

• Hyphens are allowed in topic headings and subheadings when they are part of the page or tab name. The goal is to keep the headings as short as possible.

• Topic headings should be procedure oriented for the most part.

• Overview topics allowed are (Software) Overview and (Book Name) Overview.

Note: Overview should be in every major book on the first level. If there are additional big areas or main components of the system that requires another overview, the writer may add one as long as it is consistent within the help system.

icons

• If icons are labeled, no need to place icon in Help.

Example: Toolbar buttons usually do not have labels. However, if they have hover help or alter-nate text, do not place them in the Help.

SmartPipes, Inc.


21

• If icons are not labeled, place the icon in the Help.

Example: Trash Can icon, if it has no name and is represented by symbol only, place the icon in the Help.

• If referring to icon in a procedure, the label should be capitalized and bold and the term icon should be lower case and not bold.

Example: Click the Trash Can icon.

• No icons as bullets.

• Several icons can have their own column in a table.

• Single icons can mix with text in a column.

links

• Links between topics can and are expected to be used. Keep links within the same books within the TOC unless specifically warranted.

Note: Links from topics to wizards and reports are an exception to this guideline.

• Do not include punctuation around link text as part of the link.

menu bar

Use menu bar instead of toolbar to describe the bar of drop-down menus at the top of a window. Toolbar should be used only to describe a bar with buttons that open tools.

numbered lists

• Use for all step-oriented procedures and processes.

• Use numbers with periods.

• Use default spacing between numbered list items.

• Use complete sentences that begin with a capital and end with a period.

• Must be preceded with a heading (heading 3) or a statement that ends with a colon.

• Use tables if table encompasses multiple screens or multiple steps.

• Do not use for FAQ lists.

popups

Popups are only used in FAQs of online Help systems.

procedures

• Beginning procedures:

SmartPipes, Inc.


22

• All wizards are listed under the Wizard menu. Even though some wizards may appear else-where in the UI, all procedures involving the wizards begin from the wizards menu.

• Home page Tab procedures start from the home page and not from the menu.

Example: Step 1: Click the Policies tab on the home page.

Note: If prerequisite tasks are required for the procedure to be started, you need to reference the other topics of those prerequisite tasks, and you do not have to start your procedure from the Home page.

• When documenting a procedure at the tab level, start the instructions with a verb.

• Use of OR in procedures is discouraged. Agreed upon formats include the following examples.

Example

The following is an example of steps in procedures.

1. Do one of the following

• Select Print from the File menu.

• Click the Print icon on the toolbar.

procedures within procedures

See Activating a Cisco IOS Device in the SAI Help. This layout can be used in a table (like wizards) or not in a table.

related topics buttons (6/2/03 - removed EULA)

• Copyright is not to be added as related topics.

• Copyright is not to have a related topics button.

• Follow the Online Help Related Topics Guidelines. For more information, “Appendix G: Online Help Related Topic Button Guidelines” on page 52.

required fields (6/2/03)

Required fields are not noted in the SAI/PAI Help because these fields are enforced by the software.

RoboHelp default settings

• Generate WebHelp as the default help

• The Window properties do not apply to WebHelp projects since WebHelp displays in IE or Netscape.

• Related Topics

• Use a button and popup windows to contain Related Topic information.

• Use Arial font and accept the default size.

SmartPipes, Inc.


23

spacing

• Spacing is limited by HTML code.

• Use the default spacing between all HTML tags.

• Notes/References should be on one line in this format:

Note: The system ldfjlkdf ljfld.

standard online Help sections (6/2/03)

Getting Started TopicThe Getting Started section is a book file in the TOC that contains the following topics:

• (System) Overview

• Logging Off

Note: When you are talking about logging off the system, do not capitalize the L in logging or the O in on/off.

Example: To log off to the system, click the log off button.

• Software Support

Use the Online Help index, search feature, or table of contents to search for information relating to your questions, issues, or problems. If you cannot locate help relating to your questions, issues, or problems, SmartPipes provides 24-hour-a-day, 7-day-a-week (24x7) self-directed Web-based sup-port at https:\support.smartpipes.com. The Web site provides the following information:

• Extensive technical and training documentation

• Knowledge base, including troubleshooting guides and how-to documentation

• Minor software upgrades and known issue workarounds

• “Ask the TAC” feature to request additional information

• Providing Feedback

FAQs• FAQ (book and first FAQ topic are named the same)

• FAQ heading one name (named whatever it’s called, such as Devices or Policies)

• FAQ heading two name

• FAQ heading three name... (you get the picture)

Important: For those FAQ entries that are similar, combine those entries into one entry with multi-ple links. Example: How do I create, modify, and deploy Intranet policies?

starting procedures

All wizards are listed under the Wizard menu. Even though some wizards may appear elsewhere in the UI, all procedures involving the wizards begin from the wizards menu.

Home page Tab procedures start from the home page and not from the menu.

SmartPipes, Inc.


24

Example: Step 1: Click the Policies tab on the home page.

table of contents (TOC)

• TOC organization follows the flow of the system.

• Reviewer’s discretion on TOC organization. Keep the following guidelines in mind:

• Avoid consistently having one topic in a book

• Go only three books deep

• Do not place the same topic in more than one book without discussing with Tech. Doc. Mgr.

tables

column and button names • In fields and description tables, use the word column and button when naming columns and

buttons in a table. All other naming conventions are not necessary such as: option button, list box, field, link, etc.... Column and buttons are only documented when they are not constant to the software and appear only on one or two pages and their meaning is not clear to users.

Example: Price column and Download button.

• In procedure tables, use of the label name (option button, list box, field, link, etc.) is acceptable.

Important: Columns and buttons are only included in tables when they are buttons or columns that are not obvious to the user.

table size• Tables should be set to 97%. This eliminates the problem of truncated tables when the pages are

printed.

• Modifying topics first column 16%

• Selecting a Firewall Template for (Cisco, Cisco PIX, NetScreen) first column 25%

• Viewing Standard Interfaces Templates first column 25%

• Viewing Standard VPN Templates first column 25%

• Device Console Security Groups for a (Cisco, Cisco PIX, NetScreen) first column 20%

table white spaceCell padding in tables is set at 6 pixels all around for each cell.

header/cellbody specifications• Table Header is bold, black font

• Cell body is normal tag.

• Shading is determined by the style sheet. The following classes needed to be added directly to the HTML code. (tablehead, tablehead2, tablehead3). These control all shading according to style sheet specifications.

SmartPipes, Inc.


25

table headings (6/2/03 - removed If... Then,... Entries)• Table header row names are plural

• Use the following headings in tables:

• Actions

• Areas

• Descriptions

• Fields

• Icons

• Items (to define hotspots that are neither links nor buttons - used in the Navigating System topic)

• Parts (to define a mixture of items in a table - this name may be subject to change if we find a better term)

• State (specific to SAI only - State means the state the policy is in)

• Stages

• Steps

• Tabs

Note: You can mix and match these headings in your tables. You are allowed an exception, but if you repeat the exception, you must have that exception approved by the Tech Doc Mgr.

table layoutAs necessary, you can break a table down into sections to follow the structure of the UI. Table layout depends on the system you are documenting. If you are writing for SAI, follow the table layout in the SAI Help or review the SAI Help Design Document for Quantum Scientific.

tables that include procedures in the descriptions column (6/2/03)• Tables should be used consistently throughout a Help system - so if procedures are used in one

table, they should be used in others that are similar in nature. Writer’s discretion.

• If areas grow and it is apparent that a procedure in a table should be broken out into separate topics, then writer should re-evaluate the layout for the table.

Important: Columns and buttons are only included in tables when they are buttons or columns that are not obvious to the user.

UI naming conventions and usage

Page Names SAI Help avoids the use of page names altogether. In cases where it is important to give a user a reference, SAI Help refers to the area where the user is. See the SAI Help system for examples.

ToolbarCall the following screen shot a toolbar.

SmartPipes, Inc.


26

MenusCall the following menus. The bar as a whole that includes all menus is called the menu bar.

Example: Click the wizards menu.

TabsCall the following tabs. These are specific tabs for the new SAI. PAI will have different tabs.

Example (Use this verbage exactly): Click the Service Points tab on the home page.

SmartPipes, Inc.


27

Call the following tabs within the specific tabs.

Example (Use this verbage exactly):

Step 1. Click the Devices tab on the home page.

Step 2. Click the name of the device you want to modify.

Step 3. Click the appropriate tab.

SmartPipes, Inc.


28

Call the following tabs even though they fall one level deeper than the tabs mentioned in previous screen shot.

Example (Use this verbage exactly):

Step 1: Click the Devices tab on the home page.

Step 2: Click the general tab.

Step 3: Click the device identification tab.

SmartPipes, Inc.


29

WizardsWizards do not have tabs and are located on the wizards menu.

SmartPipes, Inc.

Appendix A: Help-to-PDF ProcessTechnical Documentation Style Guide

30

Appendix A: Help-to-PDF Process

Help-to-PDF Process (3/14/2003)

The Help-to-PDF process includes transferring and formatting a RoboHelp project to FrameMaker, and then creating a postscript file, and creating a PDF.

Help-to-MS Word Conversion

Generate a printed documentation version of the RoboHelp project.

1. Open the help file in RoboHelp, the Project tab is selected.

2. Open the Single Source Layouts folder.

3. Double click on Printed Documentation. The following window appears.

4. Keep all the default settings and click the Finish button to create multiple files for each document. You want to keep the individual chapters setting because the SAI User Guide is now split into chapters and they correspond to the chapters this process creates.

Note: RoboHelp automatically creates a folder named Print Doc, and puts the MS Word print doc-uments in it.

5. After you click the Finish button, the files generate, and then the Document Wizard window displays.

6. When the View Results window displays, close the window without viewing the results.

SmartPipes, Inc.


31

Importing MS Word Documents-to-FrameMaker

Import the MS Word document into FrameMaker user guide chapters.

1. Go to: Intra server/Documents/Service Documents/SAI User Guide and Getting Started/SAI User Guide. Locate and copy to your hard drive the folder containing the previous version of the FrameMaker SAI user guide.

Note: The SAI User Guide has been split into chapters. These chapters correspond to the chap-ters that were created by RoboHelp when you converted the online help to printed documentation. The process that follows no longer uses the clipboard to copy and paste text from Word to FrameMaker. The actual “Import File” process is now used.

2. Open the FrameMaker book containing the previous FrameMaker SAI User Guide.

3. Open the getting started chapter. Keep all the text on the first page and the Getting Started with SAI heading 1. Delete the rest of the chapter’s text.

4. Place the cursor in the FrameMaker file at the end of the text on the first page.

5. From the File menu in the tool bar, select Import | File. The following window displays.

6. Locate and select the Word file you want to import into FrameMaker. This file is located in the PrintDoc folder of your Robohelp file set that you created the printed document from.

7. Select the Copy Into Document option button.

SmartPipes, Inc.


32

8. Click the Import button. The following window appears.

9. Select Microsoft Word. Click the Convert button. The following window appears.

10. Click the Import button. You do not have to change any of the default settings.

11. You need to repeat this process for each chapter of the user guide.

SmartPipes, Inc.


33

Format the FrameMaker Document

Format the document using the predefined FrameMaker paragraph tags.

FootersEnsure that the footers on the TOC and main master pages match the cover title.

1. From the tool bar, click View | Master Pages.

2. Update the footer.

Headings1. Delete all book level headings accept for level one.

Tip: Use the TOC in the RoboHelp file to determine the names of the second and third books. Type the name of the book in the Find feature in FrameMaker to quickly find the page.

2. Retag the content to use the FrameMaker styles. Headings should be adjusted as follows:

• Heading 1 tag should be applied to level 1 book titles (all other book levels should be deleted)

• Heading 2 tag should be applied to all topic titles

• Heading 3 tag should be applied to all topic section headings (i.e. Introduction, Procedure, Fields and Descriptions)

Tables1. Stretch the tables to the width of the page or to the dotted outlined border. Adjust the columns to

properly display the column headings.

Note: Tables below a step should stretch from right margin to align with the number at .25” from the margin.

2. Change the split cells back to merged cells.

3. As necessary, apply the background shade to the header row in each table. With Frame 7, this step is often not necessary. Do the following:

• Highlight the header row.

• Right click in the header row.

• Select Custom Ruling & Shading.

• From the Custom Ruling & Shading window do the following:

• Click the Fill list box, and then select 10%.

• Click the Color list box, and then select PANTONE 370 CVU.

• Click the Apply Ruling Style list box, and then select Thin.

• Click Apply

• Keep the Customer Ruling & Shading window open. Page to each table, highlight the header row, and then click Apply in the open Customer Ruling & Shading window.

Bulleted and Numbered ListsTag the existing bulleted and numbered lists to FrameMaker tags. Do the following:

1. Open the ¶ Catalog.

SmartPipes, Inc.


34

2. Remove the bullet or number carried over from the MS Word document.

Note: You must remove all numbers and bullets carried over from the MS Word document, even if they appear to be formatted properly, and replace them with the FrameMaker style.

3. Position the cursor where the FrameMaker bullet or number is to be placed.

4. In the ¶ Catalog, click the appropriate bullet or number style. For information about specific styles to use, see “Appendix B: FrameMaker Document Styles” on page 38.

Indented SentencesTag indented notes and other sentences to FrameMaker tag. Do the following:

1. Open the ¶ Catalog.

2. Place the cursor in front of the sentence that is indented where the FrameMaker bullet or number is to be placed.

Note: You must replace all MS Word document indents, even if they appear to be formatted prop-erly, and replace them with the FrameMaker style.

3. In the ¶ Catalog, click the appropriate indent style. For information about specific styles to use, see “Appendix B: FrameMaker Document Styles” on page 38.

Page BreaksAs a rule, each page break should begin with a heading 1, heading 2, heading 3, or heading 4. The exception to this rule is text or a table that carries over to the next page. If a Heading 2, 3, or 4 is located ¼ or the way up from the bottom of a page, it should be forced to start at the top of the next page, where possible.

Important: Do not press the Enter key or the Space Bar to add extra space above and below text, tables, headings, graphics etc. Always use the Paragraph Designer (Ctrl + M) to move text around.

Note: If the table separates from the header row or a blank page separates a header from the text, see the Page Break section in “Troubleshooting” on page 35.

To create page breaks for H2, H3, and H4 headings:

1. Place the cursor on the heading.

2. From the Paragraph Designer, click the Pagination tab.

3. Click the Start list box, and then select Top of the Page.

4. Click the Apply button to move the heading to the top of the page.

Converting MS Word Styles to FrameMaker Styles

1. Open the Paragraph Designer (Ctrl + M)

2. Open the ¶ Catalog window (click the paragraph ¶ symbol).

3. Place the cursor in front of the body text or heading that is using an MS Word style tag.

4. In the Paragraph Designer, click the Apply button to display the New Format Window.

5. In the New Format window, select Store in Catalog and Apply to Selection check boxes.

6. Click Create to store the MS Word style in the Paragraph Catalog. The MS Word style tag displays in the Catalog and looks similar to this example: styrsid229heading1.

SmartPipes, Inc.


35

Important: You must store the MS Word style tag in the catalog before proceeding to the next step.

7. In the Paragraph Designer, click the Paragraph Tag list box down-arrow and select the type of FrameMaker tag to be used for the text or heading.

Note: Use the following FrameMaker Service Document Styles table to determine which para-graph tag to use.

8. In the Paragraph Designer, click the Commands down-arrow, and select Global Update Options. The Global Update Option changes the styles globally.

9. From the Global Update Options window, do the following:

• Click the All Properties option button.

• Click the All Tagged option button, and then click the down-arrow to select the MS Word tag that is currently assigned to the text and that is stored in the Catalog.

• Click the Update button.

10. After you have finished converting all MS styles to FrameMaker, delete the MS styles from the FrameMaker catalog. To delete styles do the following:

• From the Catalog, click the Delete button.

• From the Delete Formats from Catalog window, select the MS style tag and click the Delete button.

• After you have finished deleting styles, click the Done button.

Important: You must delete the MS styles that you stored in the Catalog after you have finished converting the MS Styles to FrameMaker styles, to prevent the MS styles from cluttering up the FrameMaker template.

Troubleshooting

Problem Solution

Nothing pastes in FrameMaker Talk to Tech Doc Mgr because there is a way to get this to work. The cut and paste through the clipboard from Word is no longer an accurate or way to complete this task.

The page displays a header template over the text.

You need to apply the Right template to all the pages.

To apply the Right template to a master page:

1. Place the cursor on the page.

2. From the toolbar, click Format | Page Layout | Master Page Usage.

3. From the Master Page Usage window, select the Right option button.

4. Click the Apply button.

SmartPipes, Inc.


36

Save the Document and inform Tech Doc Mgr• If you converted an SAI help file, inform Tech Doc Mgr that you are finished formatting the

FrameMaker file and it is ready for review. After you have updated the document with the review comments, Tech Doc Mgr then adds the additional files (Getting Started) to the book, creates a new PDF, and then checks it into Star Team.

Note: Tech Doc Mgr may ask you to update the Getting Started pages and add them to the book.

Page Break Troubleshooting:The heading and text are separated by a blank page.

1. Place the cursor on the H2 or H3 heading.

2. From the Paragraph Designer (Ctrl + M), click the Pagination tab.

3. Click the Start list box, and then select Anywhere.

4. Click the Apply button. The text moves below the preceding heading.

Page Break Troubleshooting:A table header row is separated from its subsequent rows.Note: The idea is to separate the large row that is causing the header to split from the rest of the table. By splitting the large row, it causes the smaller row to move up under the header row.

To create a “continued” row:

1. Highlight the second row of the section of the table that immediately follows the separated header row.

2. Right click.

3. Select Add Rows or Columns from the drop down menu.

4. From the Add Rows or Columns window, select the Add option button and make sure the Above Selection displays in the Rows list box.

5. Click Add. A new row displays.

6. Highlight and cut part of Description text that can be continued to the next row.

7. Paste the Description text side of the newly created row.

8. In the left cell of the row, type the name of the previous cell and add the word (continued) after the cell name.

For example, if the name of the left cell is General, then the new cell would be named: General.

SmartPipes, Inc.


37

FrameMaker-to-PostScript

1. Verify that your FrameMaker print settings are correct. For more information, see “FrameMaker Settings” on page 45.

1. Open the book in FrameMaker.

2. From the tool bar select the Print.

3. From the Print Files in book window, select the Print button.

4. From the Print Book window select the following:

• Print Page Range ALL option button

• Print Only to file check box.

• Change the extension of the file name to .ps.

• Click the Setup button.

• From the Print Setup window, select the Apple color PS printer, and then click OK.

• Click the Print button.

Note: If an error occurs or the wrong print drive displays, contact Tech Doc Mgr.

PostScript-to-PDF

1. Open the PS file in distiller. A quick way to do this is to right-click on the .ps file in Windows Explorer, and from the menu select: Open With | Acrobat Distiller.

Important: Verify that your Distiller settings are set according to the PDF guidelines. For more information, see “Appendix C: PDF Settings” on page 42.

2. Voila! Distiller creates the PDF for you and puts it in the same folder as the .ps file.

Project Review

Inform Tech Doc Mgr that you have finished the conversion process and the PDF is ready for review. After you have updated the document with the review comments, save to the Intraserver and let Tech Doc Mgr know you’re finished with the user guide.

SmartPipes, Inc.

Appendix B: FrameMaker Document StylesTechnical Documentation Style Guide

38

Appendix B: FrameMaker Document Styles

Templates for the layout of the Cover page, TOC, and chapters are located in the Intraserver\TechDocs\Documents\Templates folder.

Warning! Do not add additional paragraph styles to the service documentation unless you explicitly request it from the Tech. Doc. Mgr.

Style Name Paragraph Style Use Style Properties

Body All body text First Indent = .25”Left Indent = .25”Space Above = 4 ptsSpace Below = 4 ptsLine Spacing = 12 ptsFont = ArialFont Size = 10 pt

Bulleted Bullets that are on the same level as the body.

First Indent = .25”Left Indent = .5”Tab = .5” leftSpace Above = 4 ptsSpace Below = 4 ptsLine Spacing = 12 ptsFont = ArialFont Size = 10 pt

Bulleted2 Bullets that are used in conjunction with numbered steps. This paragraph tag indents the bullets below numbered steps.

First Indent = .5”Left Indent = .75”Tab = .75” leftSpace Above = 4 ptsSpace Below = 4 ptsLine Spacing = 12 ptsFont = ArialFont Size = 10 pt

Bulleted3 Sub-bullets under the Bulleted2 tab. Use this only when there’s no other alternative.

First Indent = .75”Left Indent = 1.0”Tab = 1.0” leftSpace Above = 4 ptsSpace Below = 4 ptsLine Spacing = 12 ptsFont = ArialFont Size = 10 pt

CellBody Used for body text in cells of tables. Space Above = 4 ptsSpace Below = 4 ptsLine Spacing = 12 ptsFont = ArialFont Size = 10 pt

SmartPipes, Inc.


39

CellHeading Used for all headings within a table. Line Spacing = 12 ptsFont = ArialFont Size = 10 ptFont Weight = BoldCentered

Footer Paragraph tag for footer located on master page.

Font = ArialFont Size = 7 pt

Heading1 For all headings on the first level. Space Above = 22 ptsSpace Below = 22 ptsLine Spacing = 19 ptsFont = ArialFont Size = 16 ptBoldColor = Black

Heading2 For all headings on the second level.Note: In the Fields and Descriptions sections of service documentation, force each Heading2 to the top of a new page. In other sections of service documentation, force any headings that appear in the bottom quarter of a page to the next page. It is left to each writer’s discretion whether to force Heading2s that appear between the bottom half and bottom quarter of a page to the next page.

Space Above = 22 ptsSpace Below = 10 ptsLine Spacing = 19 ptsFont = ArialFont Size = 14 ptBoldColor = Pantone 2726 CVU

Heading3 Italic heading for all headings on the third level. Note: The color of this heading is lighter than the color of a Heading2.

Space Above = 10 ptsSpace Below = 4 ptsLine Spacing = 14 ptsFont = ArialFont Size = 12 ptItalicBoldColor = Pantone 2716 CVU

Heading4 For all headings on the fourth level. Space Above = 4 ptsSpace Below = 0 ptsLine Spacing = 12 ptsFont = ArialFont Size = 10 ptRegularColor = Pantone 2716 CVU

SmartPipes, Inc.


40

Indent Used for any text that is not bulleted but appears below numbered steps.

First Indent = .5”Left Indent = .5”Space Above = 4 ptsSpace Below = 4 ptsLine Spacing = 12 ptsFont = ArialFont Size = 10 pt

Indent2 Used for any text that needs to be indented below a numbered step or Bulleted tag.

First Indent = .75”Left Indent = .75”Space Above = 4 ptsSpace Below = 4 ptsLine Spacing = 12 ptsFont = ArialFont Size = 10 pt

Indent3 Used for any text that needs to be indented below a Bulleted2 tag.

First Indent = 1.5”Left Indent = 1.5”Space Above = 4 ptsSpace Below = 4 ptsLine Spacing = 12 ptsFont = ArialFont Size = 10 pt

Link Used for any text that is linked to another document or Web site.Note: This is a character format, not a paragraph format.

Space Above = 4 ptsSpace Below = 4 ptsLine Spacing = 12 ptsFont = ArialFont Size = 10 ptColor = BlueUnderlined

Numbered Used for all numbered steps (exception step 1) both in and out of tables.

First Indent = .25Left Indent = .5”Tab = .5” leftSpace Above = 4 ptsSpace Below = 4 ptsLine Spacing = 12 ptsFont = ArialFont Size = 10 ptNumbering Format = <n+>.\t

Numbered1 Used for all step 1 both in and out of tables.

First Indent = .25”Left Indent = .5”Tab = .5” leftSpace Above = 4 ptsSpace Below = 4 ptsLine Spacing = 12 ptsFont = ArialFont Size = 10 ptNumbering Format = <n=1>.\t

SmartPipes, Inc.


41

FootnoteHeadingRunInTableFootnoteTableTitleTitle

Not in used at this time. These are default FrameMaker styles that are create with each new document. Feel free to delete them if they are annoying.

SmartPipes, Inc.

Appendix C: PDF SettingsTechnical Documentation Style Guide

42

Appendix C: PDF Settings

Layout• PDF creation for hand off for publication should be completed using an Apple printer.

• Ensure that the following properties are set to determine how the PDF looks when it is initially opened (From File menu, click Document Properties, then click Open Options):

SmartPipes, Inc.


43

Acrobat Distiller 5.0 SettingsGeneral Tab

Make sure your general settings in Acrobat Distiller are set to:

SmartPipes, Inc.


44

Compression Tab

For a high-quality PDF without the enormous size, make sure your compression settings in Acrobat Distiller are set to:

SmartPipes, Inc.


45

FrameMaker Settings To include bookmarks in the PDF, make sure your FrameMaker settings for the book/file are set to:

Note: If you receive a Book Error Report in FrameMaker while trying to print the .ps file (or notice that the PDF output file is extremely large), follow the instructions to optimize the PDF size (From the Frame Format menu, select Document, and then select Optimize PDF size.).

Select the Apple PS printer, select the Generate Acrobat Data check box, and then click the PDF

SmartPipes, Inc.


46

Setup button to set the following properties:

SmartPipes, Inc.


47

SmartPipes, Inc.


48

SmartPipes, Inc.

Appendix D: Screen Capture GuidelinesTechnical Documentation Style Guide

49

Appendix D: Screen Capture Guidelines

RoboHelp Screen Capture Guidelines

• Capture using Paintshop Pro

• Save as 89a interlaced gif files

• Capture at 1028x768 DPI (do the testing on different DPI and different size monitors)

• Graphics in WebHelp files should be limited to: icons and window shots from application the WebHelp is for. Currently, there are only icons in SAI and PAI Help.

• Icons that are part of definitions should follow the colon in the definition. For example: Open: [icon here] Definition after icon.

• Capture only pertinent screen information. Do not capture SmartPipes, logo, banner, or left-pane TOC graphic.

• If adding icons to help in procedures, place all icons inline with the text.

• Do not add alternate text to icons.

• Add alternate text to all screen shots.

FrameMaker Screen Capture Guidelines

1. Use PaintShop Pro to capture a screen shot.

2. If the screen shot size is too large for your document, use PaintShop Pro to size the image.

3. Copy the image to the clipboard using Ctrl + C.

4. Open FrameMaker and paste the graphic into the Frame document as a bitmap, using Paste Special.

SmartPipes, Inc.

Appendix E: Online Help Index GuidelinesTechnical Documentation Style Guide

50

Appendix E: Online Help Index Guidelines

• Limit selections under topics to 10 entries.

• Entries should be lower-case unless they are proper nouns.

• Think synonyms. This gives the user more options; more than one-way of thinking.

• Think “implicit” synonyms (double-posting) so that you’ve provided more than one way to locate information.

• Try to find generalities within a topic and use general keywords.

• A keyword should have no more than three sub-level entries.

• Did not index copyright or intended audience topics.

• Entries should consist of key terms, main ideas, and almost always nouns.

• Avoid mix of singular and plural entries (data set, data sets), and use one consistently throughout index to keep style consistent.

• Avoid like or similar entries if they are the same. If the like entries pertain to different things, list them separately.

• Entries with one subentry should be listed with a comma and the subentry should follow on the same line

• Example: telecommuter, device

• Rather than: telecommuter

• Device

• Glossary Terms – link to a topic or link to a Glossary page. Do not link to a sole definition without a reference to a topic.

Note: For now, we are allowing gerunds until we complete more research to see what the standard is.

SmartPipes, Inc.

Appendix F: Online Help Glossary GuidelinesTechnical Documentation Style Guide

51

Appendix F: Online Help Glossary Guidelines

• Do not include notes in definitions.

• Letters that have no definitions are not included in the glossary body or as links at the top of the glossary pages.

• Use of back to top (RoboHelp arrow graphic that is gray) should be placed to the right of each glossary letter heading.

• Write definitions as complete sentences, repeating the term being defined at the beginning of the sentence.

Example: Algorithm An algorithm is a detailed sequence of actions that, when executed, accom-plishes a specific task.

• Write definitions that define the term first, then, if necessary, include information about when the term is performed or used.

Example: “Activation establishes the base configuration and sets passwords for a device. Inactive devices are activated using the activation process.” rather than, “Activation takes place when you active an inactive device using the activation process. The activation process establishes the base configuration and sets passwords for a device.”

• When defining an abbreviation or an acronym, start the sentence with the abbreviation, spell out the abbreviation or acronym in a parenthetical phrase, then define the term.

Examples:

Auth Method, short for Authentication Method, identifies the authentication method used by the security protocol.

BPS, an acronym for bits per second, is the rate at which data is sent over a communication line.

• Do not include procedural information in a definition.

Example: “Disabled Icon The disabled icon is displayed when items or user accounts in SAI are disabled.” rather than “The disabled icon is displayed when items or user accounts in SAI are dis-abled. Disabled items remain managed within the system, but cannot participate in any policies. Disabled user accounts prevent users from logging on to SAI.”

• Do not define a term that is commonly known to the target audience, unless SmartPipes uses the term in a non-conventional way.

• Do not duplicate entries (for example, base config, base configuration, and base configuration file)

• Do not include definitions of terms that are not legitimate terms, for example, do not include definitions for names of check boxes.

• Create a glossary entry titled “Special Symbols” to appear before the letter A.

• AAA - do not spell out as “triple A”, as AAA is a standard industry term.

SmartPipes, Inc.

Appendix G: Online Help Related Topic Button GuidelinesTechnical Documentation Style Guide

52

Appendix G: Online Help Related Topic Button Guidelines

1. Related topic links should be bi-directional.

Note: There are exceptions to this rule that have been approved by the Tech Doc Mgr.

2. A topic should have no more than seven and no fewer than two related topics listed under the Related Topics button.

3. Choice of Related Topics button links should considered in the following priority:

• First priority is a link to a topic in the same book

Note: If there are no topics in the same book that are appropriate for a Related Topics link, then move to the next priority.

• Second priority is a link to a topic in the Wizards book.

Note: If there are no topics in the Wizards book that are appropriate for a Related Topics link, then move to the next priority.

• Third priority is a link to a topic in a parent book.

Note: If there are no topics in the parent book that are appropriate for a Related Topics link, then move to the next priority.

• Fourth priority is a link to a topic in another book that is not a parent book.

Note: Use the priority guidelines to determine which seven or fewer should be placed within the Related Topics button. Move down the priority list according to the relevance of topics. You can have a maximum of seven topics and a minimum of two topics.

• Do not place Related Topics buttons in the Overview topics. The bullet points in the Overview topics have links already.

• Do not place a link in the Related Topics if it is already on the help page.

SmartPipes, Inc.

Appendix H: User Interface Screen Text GuidelinesTechnical Documentation Style Guide

53

Appendix H: User Interface Screen Text Guidelines

updating screen text

To update screen text for SAI Help:

1. The content writer creates a Word file with screen shots and text changes. Content writer confers with Engineering as necessary for terminology questions.

2. The Tech. Doc. Mgr. will have a date when all screen text is due.

Note: If requested content changes are extensive, the content writer can ask other writers for assistance.

3. The content writer sends the screen text to the Tech. Doc. Mgr.

4. The Tech. Doc. Mgr. reviews screen text for consistency and appropriateness and returns approved screen text to Engineering for implementation.

5. Writer forwards to development to implement.

6. Development implements screen text and Tech. Doc. is not required to verify implementation, unless time permits. Tech doc. can submit team tracks screen text that was not implemented.

guidelines

prioritiesScreen text changes are classified by the following priorities:

• High: New and updated screen text that the developer must implement for the feature.

• Medium: Updated screen text that the developer must implement for the feature after all high priority screen text changes are completed.

• Low: Updated screen text that the developer may choose not to implement. Low priority changes can be logged in the Product Feature Change Request form for future consideration.

Important: Placement of screen text is at the discretion of the developer. Any layout and design issues that need to be addressed must be brought to the attention of the Tech. Doc. Mgr. before being logged as a feature request.

high priority changesgrammatical errors

Grammatical errors include misspellings, missing or inappropriate punctuation marks, etc.

SmartPipes, Inc.


54

instructional text

Instructional text briefly describes what users must do to perform a task on a Web page. Do not write instructional text for pages other than the current page.

The examples in the following table are to be used as guidelines for writing instructional text for pages.

Notes:

• Always bold the label names of buttons, boxes, and option buttons. Do not bold the actual terms such as button or check box.

• Always use “select” with check boxes. All others use “click”.

• Do not use “quotes”. For example, don’t use: Click the “update” button.

• Do not capitalize the words that users are instructed to type in the fields. For example, use “Type a name in the Name field” rather than “Type a Name in the Name field.”

• Always write in the present tense.

• When using Note, Important, or Warning: If the screen text is using bold for certain things in the Note, Important, or Warning, follow the established style.

Element Guidelines and Examples

Check Boxes • Select the check boxes to choose the standard or custom applications to associate with this service point, and then click the Update button.

• Select the check boxes for the devices you want to delete, and then click the delete button.

• Select the check boxes, and then click the appropriate buttons.

Option Buttons

Non-Labeled • Click an option button to select a VPN security template, and then click the Update button.

• Click an option button to select a device to use with Global IP Services, and then click the Next button.

• Click an option button to display the appropriate list of devices.

Labeled • Click the New Devices option button to purchase Global IP Services for a new device.

• Click the Existing Devices option button to purchase Global IP Services for an existing device.

• Click the Primary or Billing option button to select the contact type.

List Boxes

Non-Labeled Click the list boxes to select the appropriate action sets.

Labeled Click the Selected Action Set list box to select the IKE Action Set.

SmartPipes, Inc.


55

Fields (Text Boxes) Note: Text boxes should be referred to as fields.

Non-Labeled and Multiple Fields

• Type the information in the fields, and then click the Update button.

Labeled • Type a name in the Name field, and then click the Update button.

• Type an address in the Address field, and the click the NEXT button.

Additional verbiage Display additional verbiage in a note.

• Select the check boxes to choose the hub service points for this policy.

Note: All service points must attach to the same device.

Links

To another page Most links do not have a specific label and can be identified by the column or section heading.

For consistency, the verbiage should always describe the next action the user takes after clicking the link, instead of describing the page that displays after clicking the link. .

Examples:

Multiple links

• Click the appropriate link to edit the policy.

Identifying the link by column or section headings

• Click the WAN service point link to edit the service point.

• Click the Name link to edit the policy.

• Click the Order Name link to complete an order.

To perform an action

• Click Configure Policy Schedule and Priority to configure the policy schedule.

Do not use

• Click the appropriate link to display the Devices page.

To perform an action on the current page

• Click the appropriate link to expand the selection.

• Click Check all devices to select all the devices listed.

SmartPipes, Inc.


56

To display standard help (currently not in use)

This type of link displays a standard help topic in an independent window. For information about links that display embedded help, see the Embedded help section in the Low Priority section.

Submit to the developer the help .htm file that should be pulled.

The link that displays help must not contain the same help topic that the tool bar help is already linked to.

The link located next to a section heading or other section should display help that contains general information about the entire page.

The link located next to a field should display help that contains specific information about the field.

Related Multiple Steps To avoid verbosity, combine specific multiple steps into general instructions. Users can click help if they need specific details.

Instead of:

• To select the type of network address for the service point, click the option button beside the network address, then click Next. If you want to set this service point for a single computer, select Single Host Address. If you want to set this service point for multiple computers, select Subnet Address.

Use:

• Click the appropriate option button to select the type of network address for the service point, and then click the UPDATE button.

Unrelated Multiple Actions Always use introductory phrasing with unrelated multiple actions. Do not begin sentences with action words when there are unrelated multiple actions on a Web page.

Examples:

• To rename an order, type a name in the New Order Name field, and then click the Next button. To create an order, click the Create an Order button.

• To edit the template, click the Custom VPN Service link. To delete the template, select the check box, and then click the delete button.

• To edit the policy, click the policy link. To deploy, delete, disable, or enable a policy, select the check boxes, and the click the appropriate button. To configure the policy schedule, click Configure Policy Schedule and Priority.

Tabs Instructional text is not necessary for tabs. For screen text guidelines for Tabs, see the Tabs section in the Low Priority section.

Search Instructional text is not necessary for the search option.

SmartPipes, Inc.


57

Introductory Text

Introductory text briefly introduces any of the following:

• Introduction to information on the page

• The actions the user can perform

• The results of an action

• The purpose of performing the action

• Warnings and Notes

Notes:

• Introductory text is included at the writer’s discretion.

• Do not write verbose introductory text. Introductory text should be limited to two lines at most; more lengthy explanations should be reserved for Help.

• Do not include instructional text in introductory text.

• Do not write introductory text for pages that are self-explanatory.

Examples:

• The following policies are attached to these devices:

• You must activate an inactive device before it can participate in a policy. Note: Policies that you edit must be deployed for the changes to take effect.

• Warning! Deleting the following items permanently removes them from the system.

Headings


Web page Web page headings are headings that include a string and are located at the top of the page.

The new UI design requires the previous page name in the string to be linked to the associated page.

Column Column headings are positioned above a column.

Column headings are nouns that identify the items in the column.

Verbs should be avoided in section headings because the instructional or introductory text describes the action.

Use plural nouns

Use single words

Do not use the articles A, An, and The

SmartPipes, Inc.


58

medium priority changesfield labels

Field labels identify a field. Labels are usually located adjacent to and to the left of a field. Field labels should be nouns that identify the field. The types of fields that require labels are

• text boxes

• list boxes

• read-only text

Examples:

• Name:

• Address:

Note: Do not use verbs or instructions in field names. For example, do not use “Type the Name” as a field label.

low priority changesembedded help

See the Embedded Help document for more information about embedded help.

Section Section headings are headings that label one or more sections on a single page.

Section headings are nouns that identify the section.

Verbs should be avoided in section headings because the instructional or introductory text describes the action.

Do not use the articles A, An, and The.


Hovers Hovers display what to do to the image that the cursor is hovering over. The text disappears when the cursor is moved away from the image.

Examples:

• Click to display calendar

• Click for help

• Click the image

SmartPipes, Inc.


59

Field Tool Tips Field tool tips display information specific to the field when the adjacent link or image is clicked.

Note: No tip text is needed for an object tool, which is usually an active object, such as a clanedar.

Field tool tips should not contain the following:

• links

• procedures that include more than one step

• information not related to the adjacent field

• bulleted information

• wordy explanations

Examples:

SmartPipes, Inc.


60

Tabs

Tabs identify an area in the site. Tabs should be consistent. If you see and inconsistency within a system, submit the inconsistency to the developer.

Error Messages Error messages display text that describes what the user must do to correct the error and are accompanied by an alarm image.

Hypertext links can be used in error messages to connect to a help topic to provide the user with more information about how to resolve the error. Do not link to the same help topic that is in the toolbar standard help.

Error messages should inform the user what to do and should not be accusatory or wordy.

Examples:

• Last name is required.

• You did not enter a value for a field that is required on this tab. (Vague, accusatory, and wordy)

SmartPipes, Inc.