Advice on documentation tagging?

November 11, 2008 7:47 AM

I am several weeks away from leaving my job for a new one. As a result, I need to document my current development efforts for the several folks who will be taking over my responsibilities. My challenge is how to organize documentation about individual components with some additional flexibility. I’m looking for a method, or software, that would allow a thorough initial organization of documentation notes, but also enable other slices or views: show me all bits that live on server X, show me all of the bits that support application Y, what applications depend on script Z, etc.

This will be very light documentation – more of a roadmap covering where bits live and what they do broadly. I will continue with some transitional activities over the coming months to support deeper questions.


At a coarse level, I work on 3 types of components: data scripts, relational databases, and web GIS applications. I think these three areas make a nice basic framework for a thorough initial organization. However the pieces are intertwined in many other ways that my colleagues might need to know about – by application stack, by server, by project, by programming language etc.


I think some tagging of note elements is an answer, but not sure how to implement? We do use Trac and SVN, but I have been a bit slack about keeping all of my code there. I have also used FreeMind, but it doesn’t seem flexible enough. I have seen some ontology software that works like this (click an element and the word cloud reorganizes), but I’m not sure how ideal that is for notes. I could even make a word doc with tags, which is not dynamic, but still searchable.


Thanks for any and all suggestions…

posted by jethrographic to Technology (3 answers total)

Get it all in SVN.

Run Doxygen on the C-like (C, C++, Java) bits, then put the Doxygen output into SVN.

Dump the database schema (table design, views, (s)procs, etc.), and put that into SVN. if you can, run it through an ERD tool, but I find that graphical database relations are usually superfluous except as a very high-level overview.

Document processes, i.e, "To produce (generated script X, a production release, the manual update to table pricelist we unfortunately have to do each quarter), do these precise steps."

Document any non-obvious design decisions, e.g, "The reason this script uses a temp table rather than the more obvious view is because of MySQL Bug#21853)" or "Yes, we could have used the command pattern here, but we ran into too much small-object overhead and didn't have time to write our own allocators or use the flyweight pattern").

Tie all this together in a wiki, and make sure that their are shallow links to everything (i.e., don't make your successors drill down through ten pages, try to make each page more more than four clicks from the wiki root page).

Once you have this, you can then create wiki pages "by application stack, by server, by project, by programming language etc." showing what components and dependencies are used by each of the above.
posted by orthogonality at 8:12 AM on November 11, 2008 [1 favorite]

I think orthogonality has got a good grip on the path here, but i might suggest that mind mapping software might be the best tool in the middle as opposed to the wiki. same result essentially but easier for you to quickly move through the immense amount of data you have to get out of your head.... plus modern mind mapping software allows you not only to get the thoughts out in a visual/relational way but to also easily link files, network locations etc, and then couple it all together with tags. All this such that a later user can follow the flow of the mind map or simply expose the tags that appear to lead them to what they need...
posted by chasles at 8:19 AM on November 11, 2008

Response by poster: Thanks for the great input. I got lost in several new projects in the run up to my departure and had to leave many of these ideas and my grand documentation effort by the wayside. I did develop several docs that cover (1) my applications and (2) my servers spaces at a general level and work toward each other. Working for now - thanks again for the details, hoping to carry these forward at my new gig...
posted by jethrographic at 11:35 AM on December 31, 2008