Style guidelines are described below. Some content has been adapted from the Cisco Structured Authoring Writing Guidelines:
A title is metadata that has tremendous value. Some search engines use the presence of search terms in the first 10 words of a title to rank the document. Therefore, 10 words is the recommended maximum length of a title. To maximize the retrievability of documentation:
- Start the title with the most important words.
- Start from the specific; then, move to the general.
- Capture the essence of the topic in the title.
- Make the title lean; avoid using any superfluous words.
A good title can be formatted as follows:
Product Name Release Number Type of Document
Compressed Real-Time Protocol Release 12.4 Configuration Guide
Titles should normally not include names or abbreviations representing Cisco Business Units or other organizations. Names of business units change frequently, and are not normally useful to customers referencing our documentation.
The abstract summarizes the key points that would help readers decide whether the article is relevant for their needs. The abstract can discuss the purpose of the article and the benefits described in it. Anything mentioned in this abstract should be developed in subsequent sections. The abstract is an untitled section.
This section describes the hardware or software prerequisites that must exist for the feature to work. This section may also describe “knowledge” prerequisites, such as understanding concepts or gathering information. Refer to other documents as appropriate. Describe prerequisites that apply only to an individual task in the section that describes the specific task.
This section describes restrictions or limitations that apply to the feature (such as compatibility issues) and the conditions under which the feature should not be used or under which the feature will not work properly. Describe restrictions that apply only to an individual task in the section that describes the specific task.
Information About a Product or Feature
This section lists the concepts that the user should understand in order to perform the tasks in the module. It serves as an advance organizer of the concepts. Include an introductory sentence followed by a bulleted list of concepts (even if you have only one concept). The bulleted list consists of cross-references to the appropriate paragraphs.
How to Perform a Task
This section lists the tasks documented in the module and serves as an advance organizer of those tasks. This section may also explain how to know whether a given task is required or optional. Each task-based process module contains one such section.
This section introduces the configuration example sections for the feature and includes a bulleted list of these examples.
This section refers the reader to related documentation, such as a module that describes an alternative way to do something, comprehensive examples that cross technologies, relevant RFCs, standards, MIBs, or other published documents.