Tip #11 Document Capabilities as well as limitations of reusable software assets
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.
: 
: 
: 
: 
:
Where would you document these assets? Javadoc? Separate word doc? What have you found to be more effective and maintainable?
I would recommend a lightweight tool – you can start with even a word document if you have a small set of reusable assets. What I use is a wiki – setup a page for each asset and keep updating it based on releases/iterations. Wiki is simple to use and if you are uncomfortable opening it up for anyone to edit you can have a designated owner for updating the contents and let reviewers provide feedback by adding comments on the wiki page. Javadocs are great for communicating the point-in-time state of the API but i haven’t found it convenient for tracking updates to reusable components over time.