How Do You Handle Your Enterprise Documentation?

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!

[locokamil]

... we don't.

Re:

[richdun]

Sadly, I think that would win a poll of the average /.er and others.

Re:

[Silver Sloth]

Untill you're on call, it's 4 am., the system's down, and you're trying to fix somethign that was amended by another team member . All of a sudden you become a HUGE fan of documentation, and, next morning, you tend to explain your new found zeal in no uncertain terms to the person who amended the port numbers without amending the documentation.

Re:

[SatanicPuppy]

I'm a coder and a unix admin...Unfortunately, I don't get paid to be a Unix admin (as the CFO told me, right before she cut out my raise), so while my code is documented to death, my network architecture is cryptic and erratic. Some services are enabled as I use them, but not set up to enable on boot. Some machines are in oddball locations in the building, and they're all headless, and unlabeled. Since the network infrastructure of the building is crap, I've had to pull my own cable to some machines to get

Re:

[chris_mahan]

While I completely agree with you, I now know why your nick is SatanicPuppy. Winy yet Evil.

Re:

[SatanicPuppy]

Yea, I guess it is a bit whiny...I got dumped with a completely undocumented system after the powers that be fired and drove off the people who'd maintained that system, and when I jumped in and took up the slack (the slack of three people), working crazy overtime trying to keep up some SERIOUSLY erratic, yet mission-critical applications, then to get shafted in my review because my programming output dropped?

I did feel abused. At that point I stopped making anything idiot-proof, and stopped replacing awful

Re:

[chris_mahan]

Same here...

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:

[chris_mahan]

Oh, as an aside, my boss said he had a problem. For our goals, he has to reduce the number of tickets filed against our applications by 40% next year, in order to meet his achievements benchmark. The problem? We only had 1 ticket filed last year against our applications.

Re:Easy!

[SatanicPuppy]

I hate percentage goals. What a worthless metric. If I have a great year for programming (like I did last year), then the next year my job responsibilities double and my code output drops, did I become less productive...or more?

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...

[jofny]

I'm busy creating a model for as-is IT systems, policies, procedures, configuration standards, actual settings where appropriate, etc. into an enterprise architecture tool. The toollets me relate the disparate information types, find gaps, plan change, etc. It's also a central repository for any and all IT documentation (as you described) and allows multiple people to update their bits of it as needed. It's kind of cool!

no, it's called job security....

[way2trivial]

document NOTHING.

Re:

[jofny]

Poor documentation only helps job security when it hides how truely haphazard your code/environment/IT system implementations actually are

Re:

[gclef]

If you're irreplaceable, you're un-promotable. Welcome to your dead-end job.

Re:

[camperdave]

If you're irreplaceable, you get promoted by declaration:

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:

[jofny]

Providing the name of the tool in the parent post would help: MEGA (silly sounding, yeh?) Still, it's exceedingly useful (if a lot of work to stand up initially)

Uhh, the usuals?

[toleraen]

Word [microsoft.com]+visio. [microsoft.com]

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:

[lostboy2]

mod parent up!

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:

[qwijibo]

The problem I find with using desktop based tools like this is that the documentation may exist and even be decent (in theory, I've never seen it happen in the real world), but how does anyone find the documentation? It's easy to keep things well organized for a 10 person company, but very difficult when there are over 10,000.

Re:

[walt-sjc]

Organizing the 1000 or so word documents in any kind of reasonable fashion is a nightmare.

I much prefer a wiki.

Re:

[PylonHead]

[We're so not 'enterprise' anything] But I'll say that for our small show, switching IT documentation over to a Wiki has been amazing.

* 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

[T.Hobbes]

I tried organizing textfiles for all the chapters and gifs, but it's much easier to just fork over the money and pay for the printed version. Paper makes for easier reading and browsing, too, like with any other book.

Amazon has it for $25 here:
http://www.amazon.com/Star-Trek-Generation-Technic al-Manual/dp/0671704273 [amazon.com]

Enjoy :)

Ambiguous headline

[hcdejong]

I was going to recommend Adobe FrameMaker, but that's for a different value of 'Enterprise Documentation'.

Comment removed

[account_deleted]

Comment removed based on user account deletion

Re:

[xero314]

My sentiments exactly.

Use a Wiki

[Silver Sloth]

The biggest problem with documenation is that we're all too busy keeping the systems running to write up what we did. It therefore is neccessary to use a system where

• It's easy to amend/update
• Access is controllable
• The content is searchable

All this screams Wiki to me. If you're capable of setting up the sort of VMWare system you describe then installing Wikimedia [wikimedia.org] will be a piece of cake.

Re:

[B2K3]

Exactly -- any documentation about a live network will inherently become out of date after any change. With a wiki, whoever notices a discrepancy between documentation and reality can easily fix the documentation.

Re:

[WebCrapper]

This is pretty scary because my org has been attempting to find the best way to document for the last week. With over 700 computers/servers/laptops, all seperated into regions up to 9 hours away, its a little painful. On top of that, we've noticed that the past admins haven't documented anything since 2000...

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:

[RingDev]

"Now, the bad part is, we want to create "God Books" for each one of our servers detailing EVERYTHING about it and how to bring it back from the dead, if needed."

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:

[fostware]

Actually Symantec LiveState or Acronis TrueImage Enterprise...

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:

[WebCrapper]

We currently run RAID1 mirrors on the OS drives, RAID5 on the data drives and the servers are monitored every day for dead drives. We actually had a drive fail on the exchange server and we caught it quick enough to have the rebuild done on the new drive within an hour and a half of the drive failing. Now granted, we just happened to be in the room 3 minutes after the drive failed, but it would have been caught within 3 hours. It also seems that the past admins used drives from the same lot in about 4 of th

Re:

[WebCrapper]

I've thought about this and think the same thing will happen where I am, so... I figure that, once a year, we'll cut'n'paste it into Word/Acrobat and create a "book" that we can place on our SharePoint portal. If they want a physical book, they can print that once a year, poke all the holes in it and mount it into a 3 ring binder and let it collect dust like everything else.

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:

[tom17]

What if you were in an environment where any and every change, no matter how small, is documented in a mandatory way?

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:

[Silver Sloth]

The problem with insisting on full change management protocols is the same problem as with hyper tight security. If you make things too difficult then people will find ways round it.

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:

[tom17]

In my old company, (the same one where I said the docus are spot on for certain projects) I would hate the change management process also.

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:

[qwijibo]

The half way process is to have an onerous process that you demand everyone use, and a wiki for the technical people to use, but isn't considered documentation and is frowned upon. A wiki is much easier for people to work with than searching through hundreds of emails on a topic and can be informal enough that people aren't afraid to make changes that haven't been reviewed by 25 levels of management.

Re:

[qwijibo]

It doesn't work. I work at a company that has strict requirements for following a defined process with a lot of documentation for every project. The official story is that we need to do all of this because we're a bank and SarbOx requires us to be thorough in our documentation of everything. That's +100 for creating a ton of jobs for people who perform no necessary function, but -infinity for good thinking or recognition of reality.

In reality, the official process turns a 1 month project into a 2.5+ year

Re:

[NeutronCowboy]

I'll throw in my hat for TWiki. We're not a bank, but we produce a lot of IT monitoring software, and hence, are often looked at as experts on how to run IT departments. Well.... let's just say I won't divulge the name of my company, cuz quite frankly, we barely can run ourselves. Specifically documentation is ass. The worst part is not that documentation is not there, it's that no one can find it. Occasionally, there is a drive to document something cool, or somebody just sits down and writes down his/her

Re:

[bsd4me]

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:

[marcello_dl]

That's what I did. For free in a "scratchpad wiki" at http://wikia.com/ [wikia.com]. If you have to specify sensitive data, network services details, run a wiki yourself or look for specialized hosting.

Of course i'm still the only one reading the wiki :)

Re:

[WuphonsReach]

It screams Wiki to me to... until the Wiki server is offline.

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:

[turbidostato]

"It screams Wiki to me to... until the Wiki server is offline."

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:

[pnutjam]

Wiki's need to be on a virtual machine so they can be easily moved to good hardware.

Re:

[turbidostato]

"It's a nice theory that such documentation can be kept on paper..."

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!

[Opportunist]

Generally, you'll be hard pressed to get techs to document anything. Simple reason: If it was documented, anyone could find the junk again. Not just them.

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:

[digitalhermit]

Oh no no no no...
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:

[qwijibo]

I work with some people like that. I'm sure they'll never give me any sort of position with authority because I'd just fire them all. I'd rather work with people who actually do something other than horde information. All of the smart people I've ever worked with will document things if you give them the time. The idea is that if you share the knowledge on the last project you worked on, you can be moved to another project later, instead of just doing maintenance for the last project. Also, people who

Re:

[passthecrackpipe]

Another reason you'll never get a better position is because you don't speak proper english - it's hoard, not horde. although, your own observation on this is pretty spot on as well. What will happen when they make you manager and you will fire everybody around you? I have some people on my team i'd rather see leave, but sacking them isn't the solution.

Re:

[Mikey-San]

If you work for stupid managers, you can get away with this. If they're sharp, they're going to know that you're being opaque on purpose, and this will come back to bite you in the ass.

http://www.randsinrepose.com/archives/2004/12/14/h ow_to_lose_your_job_part_1.html [randsinrepose.com]

Re:

[T-Ranger]

The best part of your post is that you think that 10AM is "the middle of the night". Rock on!

Re:

[Opportunist]

I took it to the heart what my guru said when I was still a young Padawan, "I have no problem with it when I'm told to be still here at 8am. But, please, not already."

Re:

[Opportunist]

It's not like you're getting anywhere on a tech job position anyway. But it's great when you're pondering switching jobs, you can ponder it aloud, muttering something about better payment in the other position.

It's great to have a manager's salary without the responsibility. Believe me! :)

Media Wiki

[RingDev]

I'm working hard at convincing my management to impliment a Wikipedia style documentation system. I've demoed some of the possibilities and it looks like a great tool for it. So good that I've recently installed Media Wiki for another large company looking for a documentation system. For its ease of use, configurability, and built in functionality, it is truely a great tool.

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:

[Zadaz]

Wikis are a great tool, but only as good as the information in them. If no one's documenting before the wiki, no one is going to after.

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:

[edmudama]

Sounds like someone was lazy.

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:

[truthsearch]

At my company (a software company) we use Media Wiki for all internal documentation, including server and network configurations. It's working quite well. Having free-form documentation, rather than a strictly organized hierarchical model, means people are more inclined to toss in information as they think of it. For example, if I upgrade PHP on a server it takes only a few seconds to update it in the wiki. No time wasted looking through directories or document indexes.

Re:

[djh101010]

Now if I can just convince the last supervisor that Media Wiki is better than MS Word with Track Changes turned on (shudder!).

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:

[edmudama]

Whoring, but for people too lazy to google, that macro and others are documented here:

http://meta.wikimedia.org/wiki/Word_macros [wikimedia.org]

Re:

[Degrees]

At least with older MediaWiki (ver. 1.4), it didn't search on IP addresses. That is to say, each octet of an IP address was too small for MySQL to index, so you couldn't search by IP address. If you knew you were looking for the Central Plant router, you were fine - but if you had 192.168.2.123 and wanted to find where that was used, you were s.o.l.

Another deficiency is that MediaWiki doesn't support image map. Sometimes the best way to find info is to click on the picture....

Re:

[Just Some Guy]

Now if I can just convince the last supervisor that Media Wiki is better than MS Word with Track Changes turned on (shudder!).

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

[Anonymous Coward]

Livelink [opentext.com] by Open Text [opentext.com] is simply the best solution on the market for ECM.

Confluence

[sof_boy]

We use Confluence, a wiki from Atlassian [atlassian.com]. It also integrates well with Jira [atlassian.com], their bug tracking program we also use. Both products are popular with some open source projects, the names of which elude me at the time.

Re:

[stoolpigeon]

We use both of those as well. It seems to be working pretty well as in the past - we did what has been mentioned so much above, nothing.

Trac

[AlXtreme]

Trac [edgewall.com] is what we use for network, backup and project-documentation. And bugtracking. And for browsing through our projects' code. "It just works (tm)".

TWiki too

[cleancut]

If you're just looking for a business-grade Wiki, TWiki ( http://www.twiki.org/ [twiki.org] ) is another possibility. It doesn't have the source code repository features of Trac, but it has all sorts of business-oriented modules to do all hosts of business things.

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

[sgt.greywar]

I work in a government run operation as a contractor and the documentation rarely gets beyond PowerPoint slides with the basics of each WAN site on them. We are attempting to upgrade this through the ITILS process http://en.wikipedia.org/wiki/ITIL [wikipedia.org] but have not had much luck so far.

XML - XSLT - *

[KidSock]

I'm going to need to find a solution for this as well. I want to generate a PDF manual, HTML "technotes", HTML API documentation, man pages and possibly more materials. Much of the content will appear in more than one place. It seems to me the ideal solution would use a single set of XML sources written in a custom markup specific to the content (e.g. API descriptions, code examples, etc) and then translate that into HTML, PDF, and so on using XSLT. The only problem I have right now is that I need a word pr

Re:

[Baricom]

What you're describing sounds a lot like DocBook [docbook.org]. I had difficulty getting the tool chain set up, though, so I have no practical experience using it.

Re:

[bahco]

> 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:

[value_added]

I'm going to need to find a solution for this as well. I want to generate a PDF manual, HTML "technotes", HTML API documentation, man pages and possibly more materials. Much of the content will appear in more than one place. It seems to me the ideal solution would use a single set of XML sources written in a custom markup specific to the content (e.g. API descriptions, code examples, etc) and then translate that into HTML, PDF, and so on using XSLT.

How about DocBook?

DocBook is a markup language for technica [wikipedia.org]

Re:

[slide-rule]

Our co. has some OO.o template files (*.ott) set up for developers to use ... they enter info into the form in proscribed places and then some XSLT (etc) I wrote converts the underlying *.odt file's XML into HTML. Our usage is all for in-house purposes. It is doable, but there are some minor niggles in the overall process. If the person filling in the info doesn't do what OO.o wants them to do and exactly how it wants them to, the underlying XML file -- technically preserving the info accurately -- might lo

Re:

[KidSock]

they enter info into the form in proscribed places and then some XSLT (etc) I wrote converts the underlying *.odt file's XML into

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:

[slide-rule]

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:

[KidSock]

Thanks, this is exactly what I wanted to know. Sounds like OO.o will work. DITA looks right on but I already have a schema that has some features I really need. For example I can have a function prototype like <meth><pre>struct foo *foo_new(unsigned int size, struct bar *bar);</pre></meth> and my HTML reference and man page XSL transforms will isolate each parameter making them bold (and in the future I could link each param). DITA didn't look like it had this. The way I see it I pre

Re:

[slide-rule]

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

[Bandman]

We've setup an internal Wiki site using the MediaWiki [mediawiki.org] software.

Rate my network diagram!

[Anonymous Coward]

make sure you are consistent with the industry...

http://www.ratemynetworkdiagram.com/ [ratemynetworkdiagram.com]

Please please PLEASE have a docs specialist

[Anonymous Coward]

I'm a techie, I know how to program, manage networks, install & configure domain controllers, I can rattle off hundreds of Unix CLI tools
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

[bsd4me]

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

[Colin Smith]

Two types of document management. Egroupware document management for policy style docs which describe the way things should be done and a wiki to describe the way things are actually implemented. Strategy vs tactics.

 

Vintage 1985 solution

[TheOldBear]

Well, solution is too strong a word.

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:

[RingDev]

That's the same kind of crap my supervisor is sticking too. Word docs in random places on the network. A few months ago he decided to reorganize them. That royally screwed with everyone and we are still having issues finding documents. Even with Google Desktop installed (the only way I could handle this crap) I still wind up grabbing cached copies half the time.

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 + ?

[raist_online]

I've been thinking about this for some time - my job involves being in the team looking after a big university data centre(s) and for some time now we have been seeking solutions for documenting our networks, applications, topology etc.

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

[rmerrill11]

There are several nice wiki solutions, but Confluence wiki [atlassian.com] does the best job of meeting our corporate standards, and we are in the process of migrating all our documentation to it.

The key points for us:

• Supports page level access controls
• Integrates with external authentication system (LDAP/Active Directory)
• Runs on a Java Application Server

Good luck!

Re:

[RingDev]

Media Wiki does 2/3 of that. I've seen it successfully set up on both LAMP and WIMP systems.

-Rick

Re:

[jaseuk]

I'm using Drupal with good results. AD integration, access controls, works really well for this.

Jason.

Captain,

[jar240]

what is this... earth documentation?

MediaWiki

[iJed]

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 ..

[rs232]

Put everything in the one folder and name the documents a##### where # stands for 0-9 - a true story.

Re:

[RingDev]

I have to work with a 3rd party database where all table names are 3 or 4 characters and all begin with the letter 'r'

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:

[rs232]

I have to work with a 3rd party database where all table names are 3 or 4 characters and all begin with the letter 'r'

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

[alancdavis]

I'm currently using MediaWiki in a two-pronged manner - I keep my daily and rough notes under my User: space - after 20+ years it's gotten to be a habit to make notes about /everything/ I do.

These notes become source material for the "real" Wiki entries that have all the nice (well - it's /still/ a wiki) formatting and complete information.

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

[jafiwam]

Documentation is not a project you finish.

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

[RMH101]

you need to have a policy where all departments, projects, etc *accept responsibility for keeping their documentation up to date*. have a standard document set/framework. use a standard template. standard naming convention. don't get too hung up on the technology - an excel spreadsheet and a load of text files will do the job, you don't have to use documentum or anything.
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

[smooth wombat]

I know I've written it in a previous post but when documenting a procedure, installing a piece of software for instance, my documentation starts with "Insert CD" and ends with "Remove CD". Every step along the way, every instance of clicking Yes/OK/No/Cancel/whatever, is documented.

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

[skinfitz]

How do you blueprint your entire IT infrastructure so that someone brand new could start and figure out what does what?

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

[Joe The Dragon]

A lot of places use them.

Custom Software

[dJCL]

We use the in house developers to write a proper helpdesk system with proper asset tracking. Supports multiple sites, users, mapping of physical locations, it now even updates our DNS and will soon be updating our firewall configurations.

For anything beyond that, company wiki sometimes linking to files on the fileshare.

/plug: Still looking for techs in Ottawa, need Good MS, some linux and experience on the phone. Talk to me and if your qulified, I will get you a job here - I have gotten 3 others alread

We use 80-20 document manager

[gtoomey]

http://www.80-20.com/products/document_records_man agement.asp [80-20.com] Its very much enterprise level. The inane comments here make my wonder if any of you have a job at all.

How we do IT

[thewiz]

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?

I could tell you, but then I'd have to send you to Abu Gharib.

The best organized and easy to use

[canuck57]

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:

• everyone had the same set of tools, no exceptions. If they could a