This guide provides a set of best practices that will help you with the task of
documenting a web service that is defined by a WSDL. These best practices were established by the
developers at Quarksoft, LLC who have extensive
experience in technical documentation, web services design and development.
Start With a Good Web Service Design
A good design can make documenting your web service a much easier task.
Although it might not always be an option, if you have any influence over the
design, here are some key areas that you should look out for:
- Naming conventions - The lack of naming conventions can result in very
inconsistent and cryptic names for the methods and parameters exposed by
your web service making it more difficult to document them properly. Applying good
naming conventions to the web service API will promote better readability of the
documentation.
- Global components - WSDL supports the use of XML Schema Definition (XSD)
elements and types to define method arguments. These schema components can be
defined either locally within the parent component or globally so that the component can be reused. By
using global components in your web service, you will maximize reuse and reduce the
number of components that you need to document.
And even if you do not have any control over the design, a quick review
will help you better estimate how much time it will take and set expectations
for the completion of the documentation.
Embed Comments inside Your WSDL
The WSDL documentation tag can be used to add comments to methods and arguments, while the
XSD annotation tag can be used to add comments to schema components. Both of these types of
comments can be included as part of the web service definition
making them easy to maintain as the WSDL
changes over time.
By embedding comments inside your WSDL, you create a
"self-documenting" web service definition that will be easier to understand.
Comment What You Can and Annotate Everything Else
To document your WSDL, you should add
comments to the following web service components:
- Methods - Methods are typically named as verb phrases that denote some type of
operation or process that the method performs. When you add comments to methods, describe
what that process does.
- Method Arguments - Methods can have zero or more input arguments and zero or more
output arguments. For input arguments, describe what the argument represents and how it is used
by the method. For output arguments, describe what the argument represents and how it was
provided by the method.
- Schema Components - Schema components such as elements and types are used to
define input and output arguments. While some arguments may be defined by simple types like
strings and numbers, other arguments may have a complex structure defined by a schema element
or type. Providing descriptions of the schema components used to defined arguments
allows you to document the structure of those arguments.
The descriptions that you add to these web service components should be concise and
consist of one or two sentences. If there is additional information that
is important to document, you should consider structuring your comments into two
parts: a summary description followed by a remarks section. The remarks
section can be used to include the additional information.
Although the commenting capabilities within the WSDL are quite robust, you may
not want to include all of the information that you need for documenting the
service in the WSDL itself in order to keep its size to a minimum. If this is the case
you can use a tool like TechWriter
to annotate the web service with external comments that can be merged together with
the embedded comments to produce the complete documentation.
Use a Documentation Generator
Having a self-documented web service is helpful for web service design and maintenance,
but there are many instances where you are going to need actual API
documentation. Here are a few examples:
- Design Documentation - If you are creating a web service for a client,
design documentation is typically a required deliverable.
- Web Service API Documentation - While your web service developer may have
the knowledge and expertise needed to read and understand
a WSDL, developers that wish to make calls to the web service API may not.
You will need to provide these developers with some form of documentation that
will help them use the API.
- Design Reviews - Not all participants in a design review are going to
have the same level of web service knowledge and expertise. Your subject
matter experts may not be technical at all. To facilitate such a design
review, you will need to provide documentation that anybody can read and
understand.
Fortunately there are tools like TechWriter
that can be used to generate the web service documentation automatically, leveraging the web service definitions
and the comments you've embedded.
Make Documentation Part of Your Development Process
If your project is using automated build tools like Ant, NAnt and
MSBuild, you can make generating the documentation part of the automated build
process for the system. By having the documentation as up-to-date as
the system itself, your project will benefit in the following areas:
- Knowledge Capture - While some development methodologies such as Agile
ascribe to a "document late" philosophy, projects can suffer greatly when they
lose a team member. The knowledge of a system literally walks out the
door. Documenting as you go minimizes the impact of losing a team member
and makes it easier for new team members to ramp up.
- Communication - Documentation can help communication among project team
members. The project manager can better assess the status of the project.
Subject matter experts can verify that developers are on the right track.
And mistakes can be identified earlier in the project life-cycle.
- Documentation Quality - Scrambling at the end of the project to throw the
documentation together for the final deliverable can result in the API not
being documented properly, if documented at all.
By making documentation part of your development process you will ensure
that the documentation is always in sync with the web service, even in extreme
programming environments where the WSDL is constantly changing.
For more information please visit:
