How to document a framework?

Question

I recently took over a .Net based framework that developers on my team will need to use. Unfortunately, the original developer left the company before it was finished. Now, I’m stuck with no documentation, and barely any use cases.

How should I document it so that the other developers are aware of the features and how to use them properly? What is your preferred documentation format?

Note: The framework is very business specific. It combines several APIs that are required by our other applications. Hence, there are no off-the-shelf packages that fit our needs. The work the developer completed is not foreign to me; hence, I am tasked with finishing it.

Answer 1

What kind of framework? Web? Persistence? Business specific?

An unfinished framework written by a single developer who's gone, no use cases, no documentation?

I'd recommend that you find an alternative and throw it away if you can. Find one that preferably has enough traction so there are books about it in Borders or Amazon.com. Not only will that be a better framework than anything you have, with better documentation, you'll have a better chance of finding developers who know it or want to learn it.

Who would want to be the expert in a framework that only one company uses?

Any company that's so foolish as to allow someone to put them in this position is crazy.

If it's business specific, with no alternatives, I'll retract the comment. In that case, make the docs web-based so people can get at them easily. Either write them in HTML or put them on something like SharePoint if you're a Microsoft shop.

Answer 2

You might think about creating a wiki to document the framework. That way you and the rest of the team can fill it in as you're using it.

Answer 3

@Paul Lefebvre

I would vote against the wiki. That's how we do it for our framework, and its a jumbled mess....

Answer 4

If it's a .NET environment then I'd go with Sandcastle using SHFB.

I'm not saying document the whole framework, perhaps start at the top namespaces, get a feel for the code, in important classes or interfaces write examples (use cases).

You can also create linked documents (Conceptual Content) which may help.

I'm not a big fan of documentation living too far away from code, but of course anything you write needs to be maintained (quality over quantity), nothing worse than stale or incorrect docs!

Answer 5

I don't have a good answer for this, but I'll second the wiki idea: I have thought this would be a good-ish solution, although I haven't been successful in really getting one up and running yet. I also debated Sharepoint as we are a MS-centric company, but it's hard to get enough control of a Sharepoint instance to feel confident in it, and it doesn't seem well-suited for creating collaborative reference documentation (more for just sharing simple documents over http).

I'd also second the "nothing worse than stale or incorrect docs" comment: this is a frequent problem with frameworks, and it's worse than nothing because it wastes time and you have to look at the actual code anyway.

I'm curious to see other people's responses/votes.

Answer 6

Like a dummies guide. Start very high level and then go down. Put in examples where it's complex. Write notes about system impacts of changing one thing and what else it might affect.

If you can, try to write it as if you knew nothing. Try looking up some books that specialize in creating an operations manual for a business. You probably want to do the same for this framework.... The E-Myth Manager by Michael Gerber covers operation manuals quite well and probably has some checklists you could benefit from.

Wiki's are good but the editors should be limited. Comments are good for people who have corrections. But, maybe it can work in your organization being wide open anyways.