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. Use a simple template for everyone in the team to use. We 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:
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
Location: the path to the asset in our source code control repository
Available interfaces: java interfaces, a public contract schema, 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 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.
Last updated
