Documentation: It Doesnāt Suck! by Jes Schulz Borland.
Jes writes:
Some parts of our jobs are not glamorous, but necessary. For example, I have to brush Brentās Bob Dylan wig weekly, to make sure itās shiny and perfect. Documentation is a task many people roll their eyes at, procrastinate about starting, have a hard time keeping up-to-date, and in general avoid.
Stop avoiding it, and embrace the benefits!
The most important part of documentation is starting, so Iād like to help you by giving you a list of things to document. Itās going to take time and wonāt be as fun as tuning queries from 20 minutes to 2 seconds, but it could save the day sometime in the future.
You can call this your SQL Server Run Book, your SQL Server Documentation, your SQL Server Best Practices Guide ā whatever works for your environment. Make sure itās filled in for each server, and kept up to date, and youāll soon realize the benefits
There is even a video: Video: Documentation ā It Doesnāt Suck!.
Semantic documentation isn’t the entire story behind topic maps but it is what enables the other benefits from using topic maps.
With a topic map you can document what must be matched by other documentation (other topic maps, yours or someone else’s), for both to be talking about the same subject.
And you get to choose the degree of documentation you want. You could choose a string, like owl:SameAs, and have a variety of groups using it to mean any number of things.
Or, you could choose to require several properties, language, publishing house, journal, any number of properties, and then others are talking about the same subject as yourself.
Doesn’t mean that mis-use is completely avoided, only means it is made less likely. Or easier to avoid might be a better way to say it.
Not to mention that six months or a year from now, it may be easier for you re-use your identification, since it has more than one property that must be matched.
