Revision as of 22:07, 2 March 2014

OpenStack Documentation

Documentation Contributor Guide — HowTo for first timers — Building documentation — Speciality Teams — Documentation office hours

WADL style and markup conventions

In progress......

What is WADL?

For information about WADL files, see http://docs.rackspace.com/writers-guide/content/ch_wadl.html.

For complete information about the WADL language, see Web Application Description Language (http://www.w3.org/Submission/wadl/).

Writing style

Make sure every resource has a unique ID.
Put the JSON requests before the XML requests, and the JSON responses before the XML responses. Why? JSON is used more commonly than XML.
Use sentence-style capitalization for method titles.
Put parameter descriptions inside <param> tags rather than in a table.
Be sure to describe all parameters - template, headers, plain, and so on.
Be sure to describe all response fields and response headers.
Include all possible success and error codes.
Include code examples for both JSON and XML if the method has either or both a request body and a response body.

Best practices

Spell-check the WADL.
Remove extra white-space.
Keep descriptions simple.
Use this naming convention for code samples:

JSON: resource_method_type.json. For example, for "create server request," servers_post_request.json.

XML: resource_method_type.xml. For example, for "create server request," servers_post_request.xml.

HTTP header/s: resource_method_lang_http_type.txt. For example, for HTTP headers for a "create server request," servers_post_json_http_request.txt

Validate code samples. Use oXygen to validate XML examples. Use http://jsonformatter.curiousconcept.com/#jsonformatter to validate JSON.

An API method has the following components:

URI

Title

<method name="GET" id="getVolume">
        <wadl:doc xmlns="http://www.w3.org/1999/xhtml" xml:lang="EN"
            title="Show volume details">

Use sentence-style capitalization for the title.

Follow this convention for title text:

Method	Example title
Create (POST)	Create volume
List (GET)	List volumes
Show (GET)	Show volume details
Update (PUT)	Update volume
Delete (DELETE)	Delete volume

Short description

<method name="GET" id="getVolume">
        <wadl:doc xmlns="http://www.w3.org/1999/xhtml" xml:lang="EN"
            title="Show volume details">
            <para role="shortdesc">Shows volume details.</para>

Make the short description short. Put extra content into subsequent <para> tags.

Follow this convention for short description text:

Method	Example short description	Do not use
Create (POST)	Creates a volume.	Create a volume. Creates a new volume.
List (GET)	Lists volumes.	Gets a listing of volumes. Prints a listing of volumes. Retrieves a list of volumes.
Show (GET)	Shows volume details. Shows image details. Shows the up time for a specified hypervisor.	Retrieves information about, or Gets information for.
Update (PUT)	Updates volume details.
Delete (DELETE)	Deletes a volume.	Removes a volume. Permanently destroys a volume.

@@ Line 32: / Line 32: @@
 :XML: resource_method_type.xml. For example, for "create server request," servers_post_request.xml.
 :HTTP header/s: resource_method_lang_http_type.txt. For example, for HTTP headers for a "create server request," servers_post_json_http_request.txt
-* Validate code samples. Use oXygen to validate XML examples. Use http://jsonformatter.curiousconcept.com/#jsonformatter to validate JSON.
+* Validate code samples. Use oXygen to validate XML examples. Use http://jsonformatter.curiousconcept.com/#jsonformatter to validate JSON.<br />
+<br />
 An API method has the following components:

Difference between revisions of "Documentation/WADL conventions"