Describing functions and dialog boxes
Detailed descriptions of the functions and dialog boxes offered by
any given product are always reference information, and will only
be provided in the product’s reference manual and online help.
A dedicated chapter is used to provide this information; Functions
and dialog boxes.
Microsoft style guide
Do not use as an abbreviation for dialog box.
Do not spell as dialogue in the context of a dialog box.
Microsoft Style Guide, page 277
Always call this type of a box dialog box, not
just dialog. Do not call it a pop-up window.
Microsoft Style Guide, page 277
Architecture and reuse
All functions and dialog boxes are described
according to a fixed structure. The information modules describing
purpose, description, parameters and related topics are identified
with informal headings (bridgeheads).
In XML DocBook , each
function and dialog box must be provided as a separate
section. Each information module is saved separately to allow
for reuse in other topics (tasks and concept descriptions).
XML DITA, each function and dialog box must be provided as a separate reference topic. Each information module must be
tagged to allow for reuse in other topics (tasks and concept descriptions)
using the xref functionality.
HTML, each function and dialog box must be provided as a separate
document. Each information module is saved as separate files to allow
for reuse in other topics (tasks and concept descriptions) using the iframe functionality.
Microsoft Word does
not provide adequate functionality to offer reuse. It is therefore
strongly adviced not to use Word – or similar office
text editors – to write reference information.
How to open
This is a very short description – typically one sentence –
that describes where the function/dialog box is located, i.e. on which
menu. A relevant screen capture of the menu or the menu button may
This information module comprises
one or two sentences to specify the specific purpose of the function
or dialog box. This information is frequently reused in tasks and
Do not use a figure
caption on the screen capture.
Screen captures are saved in
module is a complementary description of the function or dialog box.
The description may include tips and admonitions. In an XML-based
system, the information can be reused in tasks and concept descriptions.
If the description is extensive, you may split this information module
into separate parts, and save or tag these individually.
Each parameter provided by the function or dialog box is described
in detail using an ordered list. Secondary ordered lists may be applied
if necessary. In an XML-based system, individual parameters descriptions
may be saved or tagged separately for reuse in tasks and concept descriptions.
Common related topics are host menu,
related tasks and other functions and dialog boxes.
In XML Doc-Book,
related topics are saved in multi-language versions. in XML DITA,
the related topics are defined in the relevant relation table.
Standards for writing and grammar rules
- Microsoft Style Guide, 4th Edition, Microsoft Press, Washington, 2012, ISBN 978-0-7356-4871-5
- Chicago manual of Style, 16th Edition, University of Chicago Press, Chicago, 2012, ISBN 978-0-226-10420-1