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)

Awareness: are developers aware what reusable assets can and cannot do?  Can they understand the overall strategy behind the reuse effort? are they aware of specific assets, role for reuse in the development process, and the benefits?

Client experiences: think about the good and bad experiences. Every interaction matters, so does every medium – whether through mailing lists, bug reports, or phone calls to the reuse team.

Asset Quality: is the asset behaving the way it is supposed to? is it robust? does it allow for variability? Is it architecturally consistent with other assets? How does the potential consumer know about the quality?

Reputation: how strong are reusable assets referred to during design and implementation tasks? can clients trust the reuse team’s deliverables?

Documentation: are assets well documented? Is the document written with the reader in mind? Does it make sense – e.g. is it logically organized for a developer to follow and leverage?

Team member Behaviors: do they care about client projects like their own? Are they approachable by developers from various external teams? Ensure there is genuine empathy for business aligned projects – just like in the outside world – if you care enough and deliver, more reusable assets will be utilized in the future.

Emotional Connection: do reusable assets enhance learning and provide a sense of accomplishment for the developer/tech lead? Co-create assets whenever feasible.

Ease of use: how are assets set up? are they easily configurable? are bootstrap code generated for developers? Take care to highlight ease of integration and the multiple variability mechanisms to your audience.

This isn’t an exhaustive list but the intent was to provide some pointers when thinking about the overall reuse strategy and how that strategy needs to translate in the day to day actions that you pursue.

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.

• Evaluating the requirement and making a determination whether an existing asset can fulfill the need (as-is or with modifications) or a new one needs to be developed.
• Address risks with integrating with a reusable asset (meeting SLAs, solution complexity, etc.)
• Sharing information on available interfaces (is there a java interface? a web service?)
• Providing code samples and integration design patterns
• Provide comprehensive list of error codes and error handling recommendations – if a service throws a particular error what should the consumer do? are there specific business errors or data validation errors that the consumer needs to be aware of?
• Ensuring the consumer doesn’t starve the reusable asset’s resources. This is essential for services based reuse where multiple consumers are invoking the same service capability.
• Assistance with testing the integration (provide test data, unit test code, as well as utilities to test response time/throughput)

You can build up a service catalog and magically hope to achieve high degree of reuse and you will most likely be disappointed. Bottom line – reach out to your consumer and help them succeed. Make it easier for them to evaluate, integrate, and test. Slowly but surely your teams will start coming to you as opposed to you trying to ‘sell’ them on the value of reuse!

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

: : : : :

When documenting a reusable software asset donot only capture only capabilities. Be sure to document limitations as well. This is important because limitations directly influence refactoring work. When trying to match a user story with an existing asset the limitations will determine the extent to which you need to update the existing code in order to implement the story. Limitations are not a bad thing per se especially since you want to prioritize overcoming them within the context of a real user need. This exercise is made a lot easier when you capture the limitations ahead of time – this way you don’t have to review your code or ask several developers in order to come up with the refactorings needed.

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

: : : : :