How Do You Handle Your Enterprise Documentation? 125
An anonymous reader wonders: "I'm curious as to what tools Slashdot readers use to inventory and document their networks? What got me thinking about this is the part VMWare has been taking in data centers. You've got your SAN, various physical and logical networks, various VMs, and so forth. It just adds a new layer of complexity in terms of documentation. I'm curious as to what people have been using as for doing things like documenting how their backups work, LAN settings, FW settings, where and what runs what services, and so forth. How do you blueprint your entire IT infrastructure so that someone brand new could start and figure out what does what?"
Easy! (Score:3, Interesting)
Re: (Score:3, Insightful)
Re: (Score:1)
Re: (Score:3, Interesting)
Re: (Score:2, Funny)
Re: (Score:2)
I did feel abused. At that point I stopped making anything idiot-proof, and stopped replacing awful
Re: (Score:2, Insightful)
My managers are like "What have you done lately?"
My reply: Documentation, stability and scalability enhancement
Their reply: "What for? Deliver something to the customer!"
My reply: "I have: zero downtime in the past 12 months."
But do they care? No.
Re: (Score:2, Funny)
Re:Easy! (Score:4, Interesting)
It's like taking a poorly written application and cleaning it up, so that when you're finished, it's smaller than it was when you started. I did that a couple of months ago and this dumbass kept overwriting my new code with the old code, because he assumed that the new code must be bigger than the old code, and couldn't be bothered to look at the timestamps.
It's called an enterprise archtecture... (Score:1)
no, it's called job security.... (Score:2)
Re: (Score:2, Insightful)
Re: (Score:2)
Re: (Score:3, Funny)
Power goes out in the building...
"Hey! You know Larry, the pimply faced kid who fixes the computer stuff? Well, there's a new sign on his door that says 'Network Administrator', and he's got a parking spot now.".
Larry goes on vacation, comes back...
"Hey, Remember Larry, the network administrator. Yeah, he's now 'Director of Information Technology', whatever that means. Yeah, corner office and everything."
Team of Efficiency experts brought
Re: (Score:1)
Uhh, the usuals? (Score:5, Informative)
Of course the person creating the drawings and documents must be proficient in technical writing (aka not an idiot), because no matter what tools you have, if you don't know how to explain things, they'll be useless. Try to get your documentation peer reviewed to make sure it makes sense.
Re: (Score:2)
The only thing I'd add to the parent post is that the people documenting stuff have to be willing and able to communicate effectively, not just proficient in tech writing. That means, among other things, that they must be committed to maintaining the documentation, willing to taking the time to explain things clearly, and able to organize the documentation effectively.
Collections of undefined acronyms, cryptic phrases, and/or excerpts cut & pasted from e-mails without context into text doc
Re: (Score:2)
Re: (Score:3, Insightful)
I much prefer a wiki.
Re: (Score:3, Interesting)
* If you're looking at something, and it's wrong, you can change it without missing a beat.
* There are no worries that you're using an old version of the documentation
* It's got a search engine
* All changes are versioned
* We have all passwords information encrypted
If you make documenting something simple, people will document it. If you make it hard, people will not.
Just order it from amazon (Score:5, Funny)
Amazon has it for $25 here:
http://www.amazon.com/Star-Trek-Generation-Techni
Enjoy
Ambiguous headline (Score:2)
Comment removed (Score:3, Funny)
Re: (Score:2)
Use a Wiki (Score:5, Insightful)
Re: (Score:1)
Re: (Score:3, Interesting)
Sadly, we don't have the time (like you said) to go out and find this stuff and determine the status.
Within the last couple of hours though, I've found Technical Support software (which we need badly),
Re: (Score:2)
It's called Norton Ghost
But yeah, that documentation is incredibly helpful if you need to build the same functionality on new hardware, or if you need to upgrade a system.
-Rick
Re: (Score:2)
Both use VSS or low level agents to create images without downing the servers, and both allow restores from a SMB share.
Worth my weight in gold when multiple drives die in a RAID, and it's end of school year (certificates, reports, Curriculam Council census data - some with legal deadlines)
Re: (Score:2)
Re: (Score:2)
On top of that, every 3 years, we are required to audit our documentation to ensure that it's absolutely up to date and fresh - this'll
Re: (Score:1)
Now I realise that this ups the staffing overhead considerably as you have twice as much work to do. But that aside, do you think this would work?
What do all the ISO9001 type companies do in this respect? I have worked on projects where, although not ISO9001, were very strict with their change management process and it has to be said, the documentation was always spot on.
A lot of overhead, bu
Re: (Score:3, Insightful)
For example, in the organisation I work for make a change involves a seven page document with a five working day lead time. On the other hand, changing configuration in response to a customer complaint can be done instantaneously with the minimum of paperwork. So, if you want to get something done, get a customer to raise a com
Re: (Score:1)
Its probably one of those things thats great for managers who want to ensure everything is ducumented but awful for techies who just want to get work done.
If, however, there was a change that needed to be done straight away for whatever reason (eg, critical bugfixing) we were able to do it pretty much straight away and follow up with the documentation.
Maybe there is a pla
Re: (Score:2)
Re: (Score:3, Interesting)
In reality, the official process turns a 1 month project into a 2.5+ year
Re: (Score:2)
Re: (Score:2)
Another post mentions it, but Confluence [atlassian.com] may be a good fit. It is a Wiki, but geared towards the needs of an enterprise. Compared to other wikis, Confluence has better permission control and has better facilities for organizing articles. We have deployed several Conflence instances for clients, and all are happy.
Re: (Score:2)
Of course i'm still the only one reading the wiki
Re: (Score:2)
How do you handle documentation that is stored on a centralized bit of storage that may be inaccessible when the documentation is needed?
Are there distributed wikis?
Re: (Score:2)
Scream "paper" for that ocassions.
"How do you handle documentation that is stored on a centralized bit of storage that may be inaccessible when the documentation is needed?"
Think about it for a moment. Do you really need the "Operations manual for the Hooly Pahula branch office" when your wiki comes off-line? What for? (I won't accept as an answer "but my tech doc wiki is at our Hooly Pahula branch office", you dork). If you are serious about
Re: (Score:2)
Re: (Score:2)
Of course it is.
"but it doesn't work in practice over the long term"
I can demonstrate it works: it works for me, so it's doable.
"unless it is audited constantly."
I don't think you understood it is not the whole wiki that needs to be bulked in paper, but only the process to get the wiki online (and the whole contingency plan, if you are serious about it). The wiki is expected to change daily, but that subsection of it (wiki online and conti
Documentation? Think of your job security! (Score:4, Funny)
It's our way of securing out jobs. If you want a CD or want to know what this button does, hell, ask. You can even call us at home, even in the middle of the night, we won't even get too mad if you throw us out of our cozy beds at 10am with a call, but don't ever dare to question our way of organising things. If you ask a tech where the documentation is, he'll tip his temple and say "here".
That way you can't fire him. In today's corporate world, it's an essential job security thing to NOT document. If you have to document it, write it down and then reshuffle everything.
Sorry to be not too helpful, but that's simply how it is. At least for me. And now excuse me, I need to hunt down that (censored) tech, I need an MS-Office CD.
Re: (Score:3, Insightful)
You document, just don't document *completely*. E.g.:
1) Disable the old httpd server: rpm -e httpd
2) Rebuild the new server using the appropriate patches.
This leaves you the right to say, "I documented the process." You look like a hero for taking the initiative in just doing some documentation, and also makes the bosses stay away. If someone takes you to task for lack of detail, insist that that particular process is obvious and look bewildered that someone wouldn't know how to d
Re: (Score:2)
Re: (Score:2)
Re: (Score:2)
http://www.randsinrepose.com/archives/2004/12/14/
Re: (Score:2)
Re: (Score:2)
Re: (Score:2)
It's great to have a manager's salary without the responsibility. Believe me!
Media Wiki (Score:5, Insightful)
Now if I can just convince the last supervisor that Media Wiki is better than MS Word with Track Changes turned on (shudder!).
-Rick
Re: (Score:2)
The last three projects I with had wiki (wikis, wikka, wikum?) for all aspects of the project from spec to doc. I was told that if I had any questions, I should just annotate the wiki with my questions so people who knew could fill them in.
In every case the wiki's were about 50% stubs, and of the rest of the pages, they were all
About half way through the project, everyone
Re: (Score:2)
Wiki at some level requires the generosity of the users with their own time (or else paid to do it). After you had that exchange in email to answer a question, someone should have cut and paste the question and answer into the wiki, so that all others could read it. There's no time wasted.
Wiki doesn't have to be the QA forum, but the process needs to come full circle to get the information into the wiki if the original exchange is via another technique.
Re: (Score:3, Interesting)
Re: (Score:2)
There's a word macro out there called word2wiki, by some German guy I think. Works great, and helped me overcome that last bit of social inertia here. You can write it in word, no problem, run it through the macro, and paste the result into your wiki, it's all wikified, no (gasp!) having to learn any new tags.
Re: (Score:2)
http://meta.wikimedia.org/wiki/Word_macros [wikimedia.org]
Re: (Score:3, Informative)
Another deficiency is that MediaWiki doesn't support image map. Sometimes the best way to find info is to click on the picture....
Re: (Score:2)
Easy. In event of an emergency, is your field tech going to find it easier to use his cell phone to browse the corporate Wiki or an unviewable Word document? There have been plenty of times when I've been grateful to have web access to some information I needed.
LIVELINK BY OPENTEXT (Score:1, Interesting)
Confluence (Score:2, Interesting)
Re: (Score:2)
Trac (Score:3, Interesting)
TWiki too (Score:1)
Sys Admin Mag ran an article about tweaking its read only performance a few months ago: http://www.samag.com/articles/2006/0604/ [samag.com]
Government documentation (Score:1)
XML - XSLT - * (Score:2)
Re: (Score:2)
Re: (Score:1)
> What you're describing sounds a lot like DocBook.
Yes, you want to use XML according to DocBook's schema somewhere in the chain from data entry and modification up to the generation of all presentation forms of the information stored.
And no, you do not want to use DocBook's XML as data entry format for the technical data. (As there are [AFAIK, and please correct me if I'm wrong] no usable open source editors for XML, I doubt that you want any XML for data entry.) You can use DocBook for the narrative
Re: (Score:2)
How about DocBook?
DocBook is a markup language for technica [wikipedia.org]
Re: (Score:2)
Re: (Score:2)
Actually I was only going to use the template to create the XSLT template. Then I was going to write the XML using a custom schema BY HAND. I know that sounds a little nuts but I'm a lot faster in vim than in any word processor. Then I run the XSLT processor and generate a hopefully valid OO.o document. From there I'll tweek as necessary (does OO.o support macros?), print to PS an
Re: (Score:2)
Yes, for any reasonable "document" need, OO.o seems to support things. Figuring out the interface is another matter -- it is wholly counterintuitive how to do things looking at OO.o, but it does tables (and handles breaking them across a page), running headers and footers, TOCs, etc. The real trick to OO.o is that everything is controlled via some "style" selection, so a few things logically do drive differently than in Word. In other words, the 'zen' is different. Some things are just plain stupid: some kn
Re: (Score:2)
Re: (Score:2)
OO.o is working well enough that 99% of the company desktops now only have OO.o installed. (A big part of the equation is that we're cheapskates. ;-) We allow the HR lady to keep her copy for resume handling purposes. The two tech writers have it for legacy document purposes. Everyone else from our boss on down has OO.o. We're an IT shop, granted, but it does what we need it to.
Part of the alleged usefulness of DITA is you can extend the default functionality to add things you need. But, if you already have
Internal Wiki (Score:2)
Rate my network diagram! (Score:1, Interesting)
http://www.ratemynetworkdiagram.com/ [ratemynetworkdiagram.com]
Please please PLEASE have a docs specialist (Score:2, Insightful)
However, my writing for non-techies sucks.
Companies: once your IT departments hits about twenty people...you need to hire a technical writer or a documentation specialist.
When you get ten or fifteen geek-nerds contributing to one document (eg: "the disaster recovery scenario"), the document WILL be a mess
TDz.
Wiki (Score:2)
We have a small, internal Mediawiki installation for documenting things like this. I have found that more people actually document things this way.
I also like an online tool for tracking software versions. I have a page that lists all of the F/OSS software that we have installed, along with the installed version number, the latest version number, and the URL to the distribution page. Once a week I have an intern go through and update the latest version numbers. I get notified about changes, and then I
The way things are and the way they should be (Score:2)
Vintage 1985 solution (Score:1)
Word processing documents, scattered seemingly at random on a shared disk drive.
The organization has Lotus Notes - but does not use it [I'm thinking of the Team Room template - its sort of like the Confluence Wiki in capability]. The corporate culture is allergic to any non M$ documentation solution - even for a new flagship project that has been in progress for just over a year.
Re: (Score:2)
We have no change tracking, no access control, no versioning, etc... on most of the docs. Some of the docs are checked into Visual Source Safe, whic
Nagios + Rackview + ? (Score:1)
So far we've deployed nagios (http://www.nagios.org) for monitoring and rolled our own blog for notes / comments on servers and services.
I would like to do some more integration, possibly utilising Rackview (http://rackview.sourceforge.net). DCML (http://www.dcml.org) showed
We use the Confluence wiki (Score:1)
The key points for us:
Re: (Score:2)
-Rick
Re: (Score:2)
Jason.
Captain, (Score:1)
MediaWiki (Score:2)
While not specifically for the uses stated in the article, we use MediaWiki [mediawiki.org] for all our documentation nowadays. This has replaced the dreadful Lotus Notes as our documentation management system.
put everything in the one folder .. (Score:2)
Re: (Score:2)
I kid you not. rls for lease info, rlsb for additional lease info, rhs for historical lease info, rar for invoice info, rarb for invoice assessment info and on and on. I swear someone was on crack when they made that decision.
-Rick
Re: (Score:2)
Also keep all financial data in a spreadsheet, store it in the same folder as the executable and DLLs and erase the whole thing once a week when you attempting to drag and drop the file. Make sure to keep no backups as that'll only 'confuse me'.
Re: How Do You Handle Your Enterprise Documentati (Score:1)
These notes become source material for the "real" Wiki entries that have all the nice (well - it's
I've also used Forrest + Openoffice.org successfully in the past. Forrest accepts OOo XML as an input format. As long as you use the styles in the sample doc from the For
Document for Life (Score:4, Interesting)
It's something you do as best you can in-between other stuff. (Preferably starting with the stuff you are working on already.)
Then, the next time you do that, just go back and open the document and update it as you go through.
In our small company, we use a scattering of web sites (SharePoint or FrontPage based), network folders, individual "not done yet" documents, and a (yick) Wiki. I would like for us to use "Public Folders" on our exchange server as it doesn't involve teaching staff members to do stuff they don't already know how to do. (Some folks are not technical enough to even handle a Wiki.)
You just keep at it, and over the years you get better stuff as a collective whole. Be sure to clean out the stuff that is no longer valid, (but maybe keep it archived).
EVERYBODY needs to be writing it. I figure for every full time difficult to learn job, there's about two full time documentation jobs. So don't worry if it doesn't ever get complete. It won't, and for the most part it doesn't HAVE TO.
Also, for everyone's sake, get a dual monitor setup so you can easily document while you work on the other screen. Since our staff got two or more monitors, documentation creation rates have skyrocketed.
Of course, if you are a regulated body or get audits, it's a really good idea to review all your requirements for that once in a while so you don't waste effort doing the documentation wrong.
agreed - needs to be part of the culture (Score:2)
standardise as much as possible, ensure people have a backup in case they get hit by a bus, and store master passwords in the safe in
I document everything (Score:3, Interesting)
As far as the network itself is concerned, I'm in the process of physically visiting every pc and printer in our building, writing down its name and cable number then putting that information into a spreadsheet which also has what switch the equipment is on and what port, with each switch having its own tab. I also do updates to machines if people aren't at them.
CiscoWorks gives me the switch and port info so that is the easy part.
Before I left my previous job, I did a knowledge transfer for our SAN with the guy who would be dealing with it. I worked with him for two months so he understood how the physical connections worked, why they were connected to both sides of the SAN switch, the importance of keeping your cable numbers accurate, how to add devices to the SAN, creating LUNs, the whole works. He documented everything and expanded upon what I had already done, including screenshots, in a binder so (hopefully) anyone else who has to deal with it can follow the pictures. The best part was the physical layout of the SAN switch. All anyone had to do was have the printout, hold it up at arms length and they could see exactly what device was on what port and what adapter was on what side.
I also documented everything I did with printers so, as I told people, "When I get run over by cars who refuse to stop at the red light as I'm crossing the street, any idiot can pick up where I left off." Every printer, including model, IP, location, name, etc was kept in a spreadsheet as well. There were only 800 or so to deal with. I guess I could have memorized everything.
Sadly, I've found out that since I've left, things aren't anywhere near what they were when I was there so apparently the idiots that are still there can't follow simple directions.
So yes, documentation is critical. Everything, no matter how minute, must be written down, labeled, etc. I'm doing my best at this location to bring some of that mentality to bear but it's going to be a long and tedious process. Try doing a Visual Studio install on a machine and getting "Error code 103" or "The system cannot find _setup.dll which is necessary to complete the installation" without documentation on how to work around the messages. Of course, if the programmers who wrote the installation programs for Visual Studio would have known what they were doing, these messages wouldn't occur. But that's a different story.
You must be new here (Score:2)
You must be new here.
If any admin were to document something so that someone brand new could just step into their shoes they just lost a serious advantage to not getting 'downsized' at the next opportunity.
Reasons for getting rid of good admins usually come down to the fact we are the proverbial housewives of organisations - the only way to show you what we do is not to do it. Many ma
TPS Reports (Score:2)
Custom Software (Score:2)
For anything beyond that, company wiki sometimes linking to files on the fileshare.
We use 80-20 document manager (Score:3, Informative)
How we do IT (Score:2)
I could tell you, but then I'd have to send you to Abu Gharib.
The best organized and easy to use (Score:2)
It has been years since I have worked at an organization where they have been truly effective at dealing with Enterprise Documentation. More commonly it is a mix of emails, many dozens of shares in what seems like a billion diverse places all over including local PCs and home computer systems. All which are NOT friendly to new starts on a project or a company. Fragmented at best.
How this highly effective organization did it was simple: