Reuse Catalogue

It's all well and good saying, let's reuse.

But if you want people to do more than reuse their own stuff (which is a good start) then have to be able to quickly find whether or not there is something that exists that will meet your need.

Intuition says a web page would be ideal, maybe a wiki. Wiki's are great because anyone can edit and there isn't any imposed structure. And your librarian(s) can only have a rough idea of what your customers want. At the same time, wiki's are not so good because anyone can edit and there isn't any imposed structure. And you probably can't trust your users quite as much as you trust your librarian(s).

Suppose your ReuseLibrary? contains different 'things', including objects, but also runable services, documented business cases, reference architectures, anything. Then probably you want your catalogue pages to be similar but not the same. And you don't want your users to have to read all of them, because they won't.

So you need a search engine, and a good set of index pages will help, but only so long as the library stays small. (Probably a good thing anyway.)

Questions.

• Has anyone done this before?
• Is there off the shelf software to do this? Free? Commercial?
• What sort of information needs to be captured?

Off the cuff, I guess the minimum might be:

• Title: the name of the component
• Purpose: What problem does this address (aka Context?/Problem?/Forces?)
• Behavior: How does this component work
• Known limitations: when should this component not be used

Optionally, you could add:

• Author(s): Who created it?
• Owner(s): Who to talk to about this
• Used by: Who has used it to date
• Motive: Reasons to use this component/Reasons this component was created
• Related components: Alternatives, dependencies?
• Support: full - we regression test this regularly; on demand - if you find a bug, we'll fix it; best effort - use at own risk and we'll try to help if we can; none - we promise not to laugh out loud until you leave the room.
• Comments: Free text.

Of course, most of the above are free text anyway, so even if you have software that tries to enforce specific fields, it's more of a suggestion than an absolute requirement.

And it would be good if the software provides a question/comment/suggestion box.

---

How do the above suggestions differ from using Javadoc? I suppose that you may want to separate the classes/methods available for reuse from those you specifically don?t want to, but isn't everything up for reuse? -- MatthewFarwell

A good question. I should have said, most of what would be going into the library would not be java code. (I've clarified that in the original Question.)

And while JavaDoc (used properly) is good for describing an object that you're interested in, in my experience it's not so good for answering questions like "is there something that does X?"

On reflection, most users will already know if they want Java code or a reference architecture, so one could have different databases for each broad class of entry in the ReuseLibrary?. So one could use java-doc for java, or for any sufficiently OO code, and use something different for other types of components. Of course, the more different types of component, the more work setting up, and in keeping a common look and feel.

As an aside, is there a generic term that libraries use for things that go in their catalogue? Obviously most of the entries are books, but what about things that are not books?

The way TheCpan is set up is quite nice. On the left is a list of categories you can browse by, eg modules, scripts, distros, etc. You can drill down through that, being offered help and meta documentation on the way. Eg /modules/by-category/08_User_Interfaces/Emacs. Or you can search, and again there are different ways to search depending on what you are looking for.

--BenAveling