Home >

Writing rules: Functions and dialog boxes

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.

Topics

Related topics

Microsoft style guide

Dialog

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

Dialog box

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).

In 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.

In plain 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.

Information modules

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 be included.

Purpose

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 concept descriptions.

Screen capture

Do not use a figure caption on the screen capture.

Screen captures are saved in multi-language versions.

Description

This information 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.

Parameters

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.

Related topics

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.


Writing rules

Related topics

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

Topics