Software Reuse Quick Tip #29

Tip #29 – Automate Documentation on Reusable Assets

Happy new year 2012 🙂

What is one key reason developers have a difficult time finding and evaluating existing assets? Lack of robust documentation including what the reusable asset isn’t meant to do. Though it is a critical success factor, maintaining documentation manually is a time consuming task and is the first item that gets left out when the development team is racing to meet a deadline. It will be useful to generate documentation on service clients or library client code snippets alongside the provider code. Automate documentation as much as possible – this will come in handy when fixing bugs, integrating new consumers, as well as integrating documentation within IDEs. Here are a few examples of doing this:

  • Maven javadoc plugin for example can generate javadoc style HTML documentation for various java and web modules
  • Maven site deploy can be used to publish generated artifacts to a remote host
  • XSL stylesheets can be used to generate HTML documentation from XML schemas (XSDs) – this can be handy when exposing reusable services (e.g. using XS3P)

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: