Ask Slashdot: Documenting Scattered Sites and Systems? 114
First time accepted submitter capriguy84 writes "Six months ago I joined a small firm(~30) where I am pretty much the IT systems guy. I was immediately asked to work on couple of projects without much going through the documentation on what currently exists. So I created new wiki topics everywhere and whenever needed. I am now in a situation where information is scattered across multiple pages and there is lot of overlapping. So I have decided to start a project of re-organizing the wiki so that it makes sense to me and easily accessible for others. I am dealing with 2 disjoint sites, 4 data centers, managing all flavors of Unix, windows, networking, storage, VMware etc. Along with that I have HOWTO guides, cheatsheets, contracts, licensing, projects, proposals and other things that typically exist in a enterprise. Any tips with how to approach? Dos & Don'ts? Recommended reading?"
usage defines semantics (Score:2, Interesting)
Most used stuff on top, however you see it. (or the user community). Extremely vague advice, but just something to help keep rational.
Semantic Wiki (Score:5, Interesting)
Last year i used MediaWiki's SemanticWiki [semantic-mediawiki.org] to describe the systems, projects, human-resources, external-urls and their dependencies of a telecom.
Besides trivial parent-child relations among developers/employees, departments, etc,
i described system dependencies as semantic-relationsships with names like this: part of, invokes, build by, implements, deployed on, etc.
I described developer responsibilities with names like this: maintained by, coded by, external contact, etc.
Finally, the documentation pages and the refs to external-URLs of projects were reorganized by semantic-relations, like this: javadoc, docUrl, webApp, section of, help page, etc.
This is Strategic Architecture (Score:5, Interesting)
Capriguy84,
Over the last few years, I have worked with a service provider on what to an outsider would sound very similar. The organization's processes, applications, and information had been distributed throughout the company on an ad hoc and project basis, resulting in an irrational de facto architecture that contributed inefficiency to practically every activity. For any organization, addressing these systemic issues will always be a work in progress. Although my case differs in scale by more than a factor of 100, I think the lessons I've taken may apply for you as well.
1 - Dysfunction is not a product of the technical situation. It is a product of management. Thus, it can only be addressed by management. For you, this means you have the opportunity to lead the organization to the right outcome, and you will have to get management support to get folks to change their processes. It looks like this: a) Identify the outcomes the org is looking for. Not "FAQs on the same server," but "Knowledge Management - Processes and technology to get and KEEP key company information accessible when necessary and secure." b) Obtain management support on the outcome. c) Explain the steps and costs needed - technical and non-technical. Management must ensure that new knowledge lands in the right place and people to go to the right place for the info. d) Implement - the technology and the culture changes e) Evaluate.
2 - What you are doing is not unique to your organization. Practically every firm has this problem in varying degrees. Go scan through the book "Faster Cheaper Better" by Michael Hammer to see an articulation of the issue at a very high level - not specific to knowledge management.
3 - There are frameworks that help guide the architecture process. Have a look at TOGAF. These are model driven, and frankly, they are very hard to consume and live by. Nevertheless, the point of these is roughly the same. When the problem is too large, divide and conquer. Model the organization and subject matter by dividing it into its parts. Prioritize, strategize, etc. Having the model enables you to ensure that solutions at the micro level are in harmony with those at the macro, etc. TM Forum does this for telecoms.
4 - Since the most important part of the job is getting buy in from management and those having to live through the culture change, your soft skills are more important than the tech skills.
All this might look like killing an ant with a sledgehammer. I suggest that you take a little time glance through material on how this is done at large scale and apply whatever seems pertinent.
Good luck!
Comment removed (Score:4, Interesting)