Advice on documentation tagging?
November 11, 2008 7:47 AM 
Subscribe
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 comments total)
3 users marked this as a favorite
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]