TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
I have not been following this thread, so excuse me If I am repeating
Using brackets, braces, etc. all originate from a form a defining syntax
prior to WYSIWIG displays: Backus-Naur format (BNF). There is actually a
few versions of it, but the core is the same and has been used consistently
for the 25+ years I have written manuals.
The versions I have used were modified to reflect typography: Italics for
variables and a specific bold font for literals. All other grammar was
We used a page at the beginning of the manual for conventions.
We used the form:
init type [serial_number]
type is one of the following: basic, pro, or delux.
is the number found on the back of the unit. If
serial_number is not specified,
then you are prompted for the serial number.
Serial_number and type would be in italics indicating that you replace them
with a value.
Init, basic, pro, delux would be in a bold sans serif font t o indicate you
type them as given. The brackets indicate that serial_number is optional.
We didn't use < or > to indicate items because < and > are command line
operators in many OS's.