Systematic Reuse Success Factor #7 – Document

You have a shiny new reusable asset. You successfully refactored it and tested it as well. Now what? Take some time and document it. This will help you clarify the scope and purpose of the reusable asset. It could be a single document with all the reusable assets. Or if all your team is collocated even a flipchart would suffice to start with. This doesn’t have to be perfect from the get go.  Something lightweight that captures what the asset does and how to use it, limitations, and assumptions would be fine. If you have several external teams that you provide assets to, you can capture their application name and contact person.

It is less important what tools you use. All your documentation should be in one place. I document all the services and components using a Wiki and include the relevant set of bugs/changes for this asset from our issue tracking system JIRA. I find this convenient but I didn’t start with a Wiki. I put up a bunch of assets on a whiteboard and marked them ‘do not delete’. It hung out there for a few weeks over multiple iterations. As the list grew with new assets I moved it to the team Wiki. I use a simple template for everyone in the team to use and made minor tweaks to the basic set of fields we document based on the type of reusable asset. This keeps the documentation fairly consistent but still allows us to capture specific fields. I also tag each asset with client names so I can easily identify asset usage. The same idea can be extended to tag specific protocols, file formats, and authentication requirements so you can rapidly query things off the Wiki.

Here are the fields that I use to document our stuff on the Wiki:

  • Name: name of the reusable asset. Simple conventions used for library component, service, message
  • Version: major, minor, and patch version
  • Status: in production or in development
  • Description: brief description including any major assumptions and limitations
  • Where is it: the path to the asset in our source code control repository
  • Available interfaces: java interfaces, a WSDL document, or needs message queues.
  • Security: type of token to pass to invoke the functionality
  • input/output parameters: the path to either a language  API or xml schemas based on asset type
  • Code Samples for typical usage: source code accessing the asset’s functionality.
  • Error Handling: business and technical errors returned by the asset. Sometimes remediation steps are included as well.
  • Known Issues/Defects: this could be a bulleted list or integrated with your issue tracking system
  • Notes: Any other useful information about reusable asset you need to document

You are not “done, done” till your reusable assets are documented in a central location for all your team to access. Make this a habit every developer follows and it will soon become second nature. Now you are ready to integrate this asset with the rest of your codebase and even communicate about the new asset to folks external to your team.

Like this post? Subscribe to RSS feed or get blog updates via email.

tweet this add to post to facebook

5 Responses to Systematic Reuse Success Factor #7 – Document

  1. Social comments and analytics for this post…

    This post was mentioned on Twitter by skemsley: “You’re not done till your reusable assets are documented in a central location for all your team to access”

  2. […] as well as end-to-end business processes. Provide sample source as well as integration documentation to applications that need to leverage your processes. Do remember developers may not understand the […]

  3. […] are assets well documented? Is the document written with the reader in mind? Does it make sense – e.g. is it logically […]

  4. […] 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 […]

  5. […] them learn the core concepts and API constructs to get up and running on the platform. Provide API documentation (such as Javadocs), cheatsheets, user manuals, and code examples that demonstrate typical usage […]

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: