DocWiki:Style

From DocWiki

(Difference between revisions)
Jump to: navigation, search
(Categories)
Line 69: Line 69:
alternative way to do something, comprehensive examples that cross technologies, relevant RFCs,
alternative way to do something, comprehensive examples that cross technologies, relevant RFCs,
standards, MIBs, or other published documents.
standards, MIBs, or other published documents.
-
 
-
== Categories ==
 
-
 
-
A page can be put in a category by adding a category tag to the page (by convention, at the end of the page), e.g.:
 
-
 
-
<nowiki>[[</nowiki>Category:''Category name'']]
 
-
 
-
Substitute the actual name of the category in place of ''Category name''.
 
-
 
-
Creating subcategories takes only a few additional steps. Adding a category tag to a category page makes the edited category a subcategory of the category specified in the tag.
 
-
 
-
See the [http://meta.wikimedia.org/wiki/Help:Category MediaWiki help on Categories] for more information.
 

Revision as of 21:10, 25 April 2008

Style guidelines are described below. Some content has been adapted from the Cisco Structured Authoring Writing Guidelines:


Contents

Title

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

For example:

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.

Abstract

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.


Prerequisites

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.


Restrictions

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.


Configuration Examples

This section introduces the configuration example sections for the feature and includes a bulleted list of these examples.


References

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.

Personal tools