DocWiki:Style

From DocWiki

(Difference between revisions)
Jump to: navigation, search
(Put page in DocWiki guidelines category)
 
(One intermediate revision not shown)
Line 1: Line 1:
-
Style guidelines are described below. Some content has been adapted from the ''Cisco Structured Authoring Writing Guidelines'':
+
Style guidelines are described below. Some content has been adapted from the ''Cisco Structured Authoring Writing Guidelines''.
-
== Title ==
+
==Article 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.   
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.   
Line 19: Line 19:
Compressed Real-Time Protocol Release 12.4 Configuration Guide
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 ==
== Abstract ==
Line 63: Line 61:
bulleted list of these examples.
bulleted list of these examples.
 +
Examples should use preformatted text. Put your example in the following format:
 +
 +
'''<nowiki><pre>Your configuration example text</pre></nowiki>'''
 +
 +
==Text Conventions==
 +
 +
'''Caution''' text can be put into the following format:
 +
 +
<pre>{{caution|Your caution goes here}}</pre>
 +
 +
This text will appear as follows:
 +
 +
{{caution|Your caution goes here}}
 +
 +
----
 +
 +
'''Note''' text can be put into the following format:
 +
 +
<pre>{{note|Your note goes here}}</pre>
 +
 +
This text will appear as follows:
 +
 +
{{note|Your note goes here}}
== References ==
== References ==
Line 69: Line 90:
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 [[DocWiki:Categories]] for more information.
 +
 +
[[Category:DocWiki guidelines]]

Latest revision as of 22:44, 5 December 2008

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


Contents

Article 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

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.

Examples should use preformatted text. Put your example in the following format:

<pre>Your configuration example text</pre>

Text Conventions

Caution text can be put into the following format:

{{caution|Your caution goes here}}

This text will appear as follows:

Caution Caution: Your caution goes here

Note text can be put into the following format:

{{note|Your note goes here}}

This text will appear as follows:

Note Note: Your note goes here

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.

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

[[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 DocWiki:Categories for more information.

Personal tools