Beta

Slashdot: News for Nerds

×

Welcome to the Slashdot Beta site -- learn more here. Use the link in the footer or click here to return to the Classic version of Slashdot.

Thank you!

Before you choose to head back to the Classic look of the site, we'd appreciate it if you share your thoughts on the Beta; your feedback is what drives our ongoing development.

Beta is different and we value you taking the time to try it out. Please take a look at the changes we've made in Beta and  learn more about it. Thanks for reading, and for making the site better!

How Do You Handle Your Enterprise Documentation?

Cliff posted more than 7 years ago | from the describing-your-infrastructure dept.

Communications 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?"

cancel ×

125 comments

Easy! (2, Interesting)

locokamil (850008) | more than 7 years ago | (#17255208)

... we don't.

Re:Easy! (2, Insightful)

richdun (672214) | more than 7 years ago | (#17255414)

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

Re:Easy! (1)

Silver Sloth (770927) | more than 7 years ago | (#17255614)

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.

Easy!-Hold my hand. (0)

Anonymous Coward | more than 7 years ago | (#17257890)

Sounds to me like most of the tools that "technical people" use should be as self-documenting as possible(1). All your "configuration" tools should not only "configure" but document that change in a central place.*

*If memory serves, gnome-config had that as one of it's goals.

(1) They do this in part by being the gatekeeper between action and result. Now that doesn't address procedures, but even that could have a helping hand similiar to macro programming. You fill in the blanks.

Re:Easy! (2, Interesting)

SatanicPuppy (611928) | more than 7 years ago | (#17257000)

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 adequate bandwidth, and that means that servers aren't necessarily plugged in where you'd think they would be.

All the Win admins, who tell the CIO they don't need to pay me to do admin work when everything is working perfectly, and then worship my skills when something breaks, can figure it out themselves if I'm not around. I'm tired of babying them, and giving them detailed written instructions for stuff that they should damn well know how to do.

Re:Easy! (2, Funny)

chris_mahan (256577) | more than 7 years ago | (#17258144)

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

Re:Easy! (1)

SatanicPuppy (611928) | more than 7 years ago | (#17260092)

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 kludges with stable configurations. I stopped programming in one programming language. I stopped using one crontab. I stopped caring if applications had critical directory mount chains that crossed multiple machines. Most importantly, I stopped documenting anything.

Looking at my work from a purely functional standpoint, no one could have any complaints. Everything does exactly what it's supposed to. But the robustness and redundancy that are the hallmarks of a system that is done correctly are gone, and the beauty of it all is, I've got a nasty performance review in my file blasting me for not focusing on "my job", so I fricking dare anyone to complain about anything that is not part of my official responsibilities.

Re:Easy! (2, Insightful)

chris_mahan (256577) | more than 7 years ago | (#17261360)

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:Easy! (2, Funny)

chris_mahan (256577) | more than 7 years ago | (#17261402)

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! (3, Interesting)

SatanicPuppy (611928) | more than 7 years ago | (#17261530)

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.

Re:Easy! (1)

j35ter (895427) | more than 7 years ago | (#17259562)

Amen, brother. My firm was looking for a Python coder with some *NIX knowledge.
My predecessor left me with a (400 Linux subsidiaries) undocumented network, a totally undocumented 500KB curses based Python program to a freakingly normalized Oracle database, "designed" by a FoxPro enthusiast, and an Interbase DB....Oh my...
Now there are 4 of us working to keep this stuff working (My colleagues - .Net guys doing Java - are banging their heads trying to alter our midtier code...Someone hardcoded the year - "06" being the last :)
This leaves me working as an Oracle and Interbase dba, Unix Sysadmin, Network admin and Python Guru.
So, Yes, I understand your trouble.
BTW, my salary would make a U.S. admin smile

Sounds a lot like Indian outsourcing firms. (0)

Anonymous Coward | more than 7 years ago | (#17256524)

That's the basic policy of the four different Indian outsourcing firms we have dealt with. Not one of them provided suitable documentation.

For one project, they just ran an early version of the Java code they developed through Borland Together or some other tool to generate UML class and sequence diagrams. Mind you, UML isn't exactly that useful in the first place, but it's even worse when the diagrams you do have correspond poorly to the actual source code you're dealing with. Then again, most of the code we've gotten from them has been complete shit, requiring significant refactoring and clean-up on our end.

On one other project they provided us with a lot of documentation. At first glance, it looked quite useful. But then as we started reading it, we realized that they had taken the documentation for a similar project they had done for some other company, changed a few class names here and there, and said it was for our project. The correspondence between actuality and what the documentation stated was virtually nil.

Most of the projects we've had them work on have come back without comments in the source code of any type. But perhaps that's better than the one project we got back where somehow they had transliterated Hindi, Urdu or some other language using the Latin alphabet, and commented the code with what looks like nothing but gibberish to us English-speaking developers. Even the one fellow on our team who is directly from India couldn't make sense of it.

I don't know why our management continues to deal with those companies. Their developers obviously can't code worth shit, and the documentation they give us is lousy, if not outright harmful.

Re:Easy! (1)

Atrox666 (957601) | more than 7 years ago | (#17259446)

That's the sad reality of the industry.
Information Technology people are supposed to be able to do their jobs effectively without information.
It's sort of like hiring a carpenter and not giving them any proper wood..then blaming the carpenter for not growing a tree out of their ass.

The mistakes I usually see are these:
-Not having any documentation
-Storing it in a big fileshare directory (not a bad first step toward having documentation)
-Storing it in a different place for every group
-Adding it to a big web site that only web admins can edit
-Punishing low level techs for updating documentation in their call statistics
-Using systems that do not allow peer updates (the ONLY way to keep a knowledge base current)
-Using systems that don't allow keyword/phrase searching
-Using systems that don't allow for odd formats like pdfs or visio docs
-Designating editors/reviewers and then not allocating any time to do the actual work on an ongoing basis

I also get a lot of push back from techs who think that the only reason everything is being documented is so that their job can be given to someone in India. Usually they are absolutely correct in that assumption.

Maybe the more relevant question is how we can prevent smart people from wasting their lives working for morons.

Re:Easy! (1)

tootired (91527) | more than 7 years ago | (#17260696)

Brilliantly put, but I'd like to add one thing.

Dumb Easy to use-If the system requires any learning curve, forget it. People who've been here forever don't want to learn anything new and will resent it and not use it.

I recently implemented DekiWiki for process and code documentation and everyone loves it.

It's called an enterprise archtecture... (1)

jofny (540291) | more than 7 years ago | (#17255222)

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.... (1)

way2trivial (601132) | more than 7 years ago | (#17255382)

document NOTHING.

Re:no, it's called job security.... (2, Insightful)

jofny (540291) | more than 7 years ago | (#17255600)

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

Re:no, it's called job security.... (1)

gclef (96311) | more than 7 years ago | (#17256506)

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

Re:no, it's called job security.... (2, Funny)

camperdave (969942) | more than 7 years ago | (#17258210)

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 in to improve work flow...

"Hey, did you hear? Larry got canned. No, not that Larry, the computer Larry. Turns out he was, how did they say it, 'holding the corporate infrastructure hostage'. The boss said my idea about getting those consultants in will save them big bucks. Guess who has the corner office now, baby!"

Re:It's called an enterprise archtecture... (1)

jofny (540291) | more than 7 years ago | (#17255856)

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? (4, Informative)

toleraen (831634) | more than 7 years ago | (#17255246)

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:Uhh, the usuals? (1)

lostboy2 (194153) | more than 7 years ago | (#17255852)

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 documents scattered across a hundred directories and subdirectories (or printed and stuffed into a 3-ring binder) is not useful. And sometimes old/incorrect/outdated documentation is worse than no documentation.

Re:Uhh, the usuals? (1)

qwijibo (101731) | more than 7 years ago | (#17256352)

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:Uhh, the usuals? (2, Insightful)

walt-sjc (145127) | more than 7 years ago | (#17260412)

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

I much prefer a wiki.

Re:Uhh, the usuals? (0)

Anonymous Coward | more than 7 years ago | (#17258700)

Right, until it is time to find those documents; which by the time you have 100-1000 different people writing the documentation, are scattered around a bunch of different network shares and in different folders on those network shares. Finding the documents becomes a nightmare, and searching for content in them is nearly impossible.

There isn't a problem with using word and visio (unless you a network that has a decent number of Linux and Unix systems), if you find a reasonable way to manage those documents. The system used should keep all documentation in a centralized location, and should be easily searchable.

Another issue to take into consideration is collaboration. Word+visio don't offer too much in terms of easy collaboration. Sure, you can send around documents in email, or use sharepoint, but multiple people editing the same document gets hairy quick.

Wikis can solve a lot of the problems. They are a centralized documentation system with good collaboration tools and are very searchable. What many wikis are missing though is a good way to organize prior (non-wiki) documentation.

MediaWiki is a pretty good tool for the job imo, if it isn't a problem for everyone to be able to read all of the documentation.

Just order it from amazon (4, Funny)

T.Hobbes (101603) | more than 7 years ago | (#17255250)

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 (1)

hcdejong (561314) | more than 7 years ago | (#17255268)

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

Scuse me? (2, Funny)

justkarl (775856) | more than 7 years ago | (#17255290)

....What documentation?

Re:Scuse me? (1)

xero314 (722674) | more than 7 years ago | (#17256014)

My sentiments exactly.

Use a Wiki (5, Insightful)

Silver Sloth (770927) | more than 7 years ago | (#17255308)

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:Use a Wiki (1)

B2K3 (669124) | more than 7 years ago | (#17255420)

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:Use a Wiki (2, Interesting)

WebCrapper (667046) | more than 7 years ago | (#17255630)

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), that will scan your network for all kinds of info. I won't list anything specific because we haven't gone with anything yet nor do I want to look like I'm advertising. But, these packages look pretty promising and some offer reporting ability.

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. Talk about a pain in the ass. Although, I never thought of a Wiki. Since we want to stand one up anyway, that would be interesting. I'd be interested in seeing anything like this anyone has created.

Re:Use a Wiki (1)

RingDev (879105) | more than 7 years ago | (#17256816)

"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:Use a Wiki (0)

Anonymous Coward | more than 7 years ago | (#17261618)

we want to create "God Books" for each one of our servers detailing EVERYTHING about it

As a trial we have documented one of our servers like this using a wiki. The techs are pleased with the results and we will likely document all servers this way. One of the nice aspects is that you can add little notes via linking without cluttering the documentation.

Management is less pleased. I think they were expecting an actual book.

Re:Use a Wiki (1)

tom17 (659054) | more than 7 years ago | (#17255644)

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, but if it works and can save huge problems down the line then maybe worth it?

Re:Use a Wiki (2, Insightful)

Silver Sloth (770927) | more than 7 years ago | (#17255802)

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 complaint to avoid the paperwork.

As such over complex systems are self defeating.

Re:Use a Wiki (1)

tom17 (659054) | more than 7 years ago | (#17256060)

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 place for a "half-way" type cm process where insignificant or bugfix changes changes can be made quickly with the cm/ducumentation process following thereafter. I dunno, i'm just waffling really :)

How about develop some system that documents the system for you.. You make a change to a port number and the docus pick it up automagically :)

Re:Use a Wiki (1)

qwijibo (101731) | more than 7 years ago | (#17256430)

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:Use a Wiki (2, Interesting)

qwijibo (101731) | more than 7 years ago | (#17256036)

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 project (already past year 2, end still not in sight). The 6+ month projects could never be done using the official methodology, so they're clandestine. The strict requirements have caused us to abandon all reason and good judgement and just do as little as possible across the board, resulting in insecure environments that are not administered with applications that are held together with duct tape. There's such a strong push for no single point of failure from an official company perspective that it results in many key people never having time to train anyone else, so major pieces of functionality and knowledge are lost everytime someone leaves. This creates an environment where people don't want to stay.

One of our DBA's set up TWiki to document things. It looks decent and seems like a good idea to me. It's probably noncompliant with company policy on many fronts, so it probably can't be the official repository here, even though it's many times better than what we do have. I like the idea of anyone being able to find the documentation and fix it as well as using version control to allow anyone to see past revisions in case someone's "fixes" are wrong.

That's way better than the methodology we use where all the documentation has to be watered down to the point where no useful or accurate information is presented, they admit that form over function is the rule for the entire process, and no one could ever find documentation for any project anyway, because there is no common place to put the useless powerpoints.

Re:Use a Wiki (1)

NeutronCowboy (896098) | more than 7 years ago | (#17256862)

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 amassed wisdom. The problem is, those documents then vanish into a multitude of document repositories. There are knowledge bases, shared drives, several different document storage solutions, and a couple of Wikis that all hold various docs, some of which are duplicates, and none of which (with the exception of the Wikis and the knowledge base) can be properly searched. Now we're trying to standardize on a Wiki, but for some reason, the nitwit in charge of it tries to make it into file share with a web interface. I'd love to know how other people store and access their documentation, because for me, that's problem #1.

Use Dspace. (0)

Anonymous Coward | more than 7 years ago | (#17258084)

For you I'd recommend a digital repository [rlg.org] like Dspace [dlib.org] .

Re:Use a Wiki (1)

bsd4me (759597) | more than 7 years ago | (#17257080)

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:Use a Wiki (1)

marcello_dl (667940) | more than 7 years ago | (#17259816)

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

Documentation? Think of your job security! (3, Funny)

Opportunist (166417) | more than 7 years ago | (#17255344)

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:Documentation? Think of your job security! (2, Insightful)

digitalhermit (113459) | more than 7 years ago | (#17255944)

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 do it. "What? Document a rebuild? Does that mean I need to tell them how to turn on the computer too?"

  Math teachers have been doing this for years:

I'll leave the details as an exercise for the reader.

Re:Documentation? Think of your job security! (1)

qwijibo (101731) | more than 7 years ago | (#17256150)

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 whose only value comes from the information they horde are the first to go when the system gets phased out.

Re:Documentation? Think of your job security! (1)

passthecrackpipe (598773) | more than 7 years ago | (#17257340)

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.

Only shitty developers don't document. (0)

Anonymous Coward | more than 7 years ago | (#17256330)

I know you're joking, but the fact of the matter is that it's really only job security for the shittiest of developers.

Those who know what they're doing are often happy to document what they've come up with, as it will clearly show that they're bringing a high degree of value to the firm. That's the best job security there is.

Re:Documentation? Think of your job security! (1)

dummkauf (936539) | more than 7 years ago | (#17258360)

Thats a great philosophy. Only one problem with. What happens when it comes time to promote someone. If you're the only one who knows the systems, it probably wouldn't be a smart move to give you a new position. So you're right, you have job security, but also can't go anywhere.

Re:Documentation? Think of your job security! (1)

Mikey-San (582838) | more than 7 years ago | (#17259300)

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:Documentation? Think of your job security! (0)

Anonymous Coward | more than 7 years ago | (#17260842)

You had several excelent replies to your "job secirity" comment.
You are right, it's true, and I have witnessed it myself.

But IMHE (Experiance), such a tactic never prevented anyone from being fired.

Each time I saw someone get fired, they extract the hard drive, put a name on it and place it on a stack of similar drives.

If someting goes wrong instead of "They just have to call me to save them", they rather say "What an incompentent he was, lets bring in a consultant for an unbiased opinion".

Of course the consultent NEVER say "hire back this God like IT guy". It is more like, "what an incompentent moron he [technical blaber] and then [more technical blaber], but I know the perfect solution. Just buy X and let me code Y and all your [technical blaber] problems are solved."

The sad thing is that after a few months everyone complaints on how much it cost (usually 4 to 5 times more than expected) ... but since everything works fine, without any more IT guy hanging around, they take the hit and repeated when necesary.

Re:Documentation? Think of your job security! (1)

T-Ranger (10520) | more than 7 years ago | (#17261242)

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

Media Wiki (4, Insightful)

RingDev (879105) | more than 7 years ago | (#17255348)

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:Media Wiki (1)

Zadaz (950521) | more than 7 years ago | (#17256112)

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 just skipped asking questions on the wiki because it was a waste of time when you needed a ready answer and did it in email.

These weren't an enterprise situation, but it still holds. You need to have the discipline and management in place, or whatever technology you use will not help you.

Re:Media Wiki (1)

edmudama (155475) | more than 7 years ago | (#17258112)

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:Media Wiki (2, Interesting)

truthsearch (249536) | more than 7 years ago | (#17256230)

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:Media Wiki (1)

djh101010 (656795) | more than 7 years ago | (#17257992)

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:Media Wiki (2, Informative)

Degrees (220395) | more than 7 years ago | (#17260732)

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

LIVELINK BY OPENTEXT (1, Interesting)

Anonymous Coward | more than 7 years ago | (#17255362)

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

Re:LIVELINK BY OPENTEXT (0)

Anonymous Coward | more than 7 years ago | (#17261066)

Livelink has been tried 3 times in our very large organization. It's never made it out of the lab because of technical issues. It's a simplistic piece of garbage.

Confluence (2, Interesting)

sof_boy (35514) | more than 7 years ago | (#17255398)

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:Confluence (1)

stoolpigeon (454276) | more than 7 years ago | (#17256360)

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 (2, Interesting)

AlXtreme (223728) | more than 7 years ago | (#17255470)

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 (1)

cleancut (16625) | more than 7 years ago | (#17256244)

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 (1)

sgt.greywar (1039430) | more than 7 years ago | (#17255502)

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 - * (1)

KidSock (150684) | more than 7 years ago | (#17255506)

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 processor that understands XML and can display content with tables footers, footnotes, SVG graphics, etc. Then I can create a template document, write the XSLT transform and generate the manual and convert it to PDF. The only problem is the only product that I know of that can do all the footers, TOC, footnotes, tables, graphics, etc AND import and export XML is Microsoft Word 2003 but I'm not excited about the price and I don't usually have a Windows machine on in the office I'm in.

Has anyone else been doing something similar? Any tips for me? I'm going to check out OpenOffice first but based on previous experiences I'm a little skeptical that it can do more than create "Lost Dog" signs.

Re:XML - XSLT - * (1)

Baricom (763970) | more than 7 years ago | (#17255746)

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:XML - XSLT - * (1)

bahco (522962) | more than 7 years ago | (#17256436)

> 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 part of the documentation, but the source of the technical data should be in a vocabulary that is tailored to your environment, be it XML or otherwise. This technical data you transform to DocBook before transforming it to man page, PDF, ...

At least, that is how I would do it, if I had the time. ;-|

DocBook editors (0)

Anonymous Coward | more than 7 years ago | (#17260698)

XMLMind ships a sorta wysiwyg DocBook editor: http://www.xmlmind.com/xmleditor/ [xmlmind.com]

If you like wrassling with the tags, jEdit is GPL and quite usable, IMO. If you're an Emacs-head, nxml-mode (http://thaiopensource.com/download) is probably what you want.

If you don't mind forking out a /little/ bit, like working with tags, and work for an educational institution, (http://www.oxygenxml.com) might
well be for you. Features up the wazoo, and connects to all sorts of different things.

The recent DocBook XSLT bundles do ship something that purports to almost round-trip simple "Word ML"; I don't suppose there's been enough interest in working on OpenOffice's DocBook filters, but they do exist.

Re:XML - XSLT - * (1)

value_added (719364) | more than 7 years ago | (#17256144)

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 technical documentation. It was originally intended for authoring technical documents related to computer hardware and software but it can be used for any other sort of documentation. One of the principal benefits of DocBook is that it enables its users to create document content in a presentation-neutral form that captures the logical structure of the content; that content can then be published in a variety of formats, including HTML, PDF, man pages and HTML Help, without requiring users to make any changes to the source. [wikipedia.org]

As for the original question, I prefer a simple binder with copies of the output of whatever program can be used to generate the output: dmesg, netstat, ifconfig, Windows whatever, etc. Not exactly enterprise, but it works at a smaller scale. Past that, you're looking at first defining what you're going to document, the form of that documentation, how it's distributed or made available, blah blah blah. That's the kind of job best left to a committee or by the folks upstairs whose job it is to define and set policies.

Re:XML - XSLT - * (1)

slide-rule (153968) | more than 7 years ago | (#17258186)

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 look a little shuffled up to your first-draft XSLT process. You can really only go so far in the XSLT domain before you just have the process throw an error message, after which you walk down to someone's office and smack their knuckles for doing it the wrong way.

Internal Wiki (1)

Bandman (86149) | more than 7 years ago | (#17255584)

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

Rate my network diagram! (1, Interesting)

Anonymous Coward | more than 7 years ago | (#17255624)

make sure you are consistent with the industry...

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

Please please PLEASE have a docs specialist (2, Insightful)

Anonymous Coward | more than 7 years ago | (#17255632)

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 (1)

bsd4me (759597) | more than 7 years ago | (#17256148)

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 we can make the decision about whether to install the new version.

Wiki-RSS. (0)

Anonymous Coward | more than 7 years ago | (#17258310)

"Once a week I have an intern go through and update the latest version numbers. I get notified about changes, and then I we can make the decision about whether to install the new version."

One of the jobs of an engineer is to take known parts and put them together in numerous ways. For the above I'd recommend RSS. You will still need the human in the loop to determine what to update and what to leave alone, but you've just simplified one step.

The way things are and the way they should be (1)

Colin Smith (2679) | more than 7 years ago | (#17256170)

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 (1)

TheOldBear (681288) | more than 7 years ago | (#17256212)

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:Vintage 1985 solution (1)

RingDev (879105) | more than 7 years ago | (#17257418)

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, which is atleast something, but it means making a one line change to a document is now a 5 minute process. The supervisor is very insistant that 'Track Changes' is turned on, even though it makes documents un-readable, and provides no real value for version tracking on the document.

In any case, documentation through assorted Word documents has to be one of the worst solutions I've had to deal with in an enterprise environment. Even Lotus Notes has better tools for this type of information colaboration.

-Rick

Nagios + Rackview + ? (1)

raist_online (522240) | more than 7 years ago | (#17256248)

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 some promise but now seems dead.

If anyone is further down this path, I'd really appreciate some input, otherwise I can release the first stage design specs from our project and see if we can build a community around that.

We use the Confluence wiki (1)

rmerrill11 (308424) | more than 7 years ago | (#17256522)

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:We use the Confluence wiki (1)

RingDev (879105) | more than 7 years ago | (#17257480)

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

-Rick

Captain, (1)

jar240 (760653) | more than 7 years ago | (#17256652)

what is this... earth documentation?

MediaWiki (1)

iJed (594606) | more than 7 years ago | (#17256680)

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 .. (1)

rs232 (849320) | more than 7 years ago | (#17256908)

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

Re:put everything in the one folder .. (1)

RingDev (879105) | more than 7 years ago | (#17257858)

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:put everything in the one folder .. (1)

rs232 (849320) | more than 7 years ago | (#17258576)

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 (1)

alancdavis (677086) | more than 7 years ago | (#17256910)

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 Forrest distribution it renders cleanly.

Forrest can then output in a variety of formats, including PDF, to make generating offline site documentation for disaster recovery guides a /much/ simpler task - which means there's a better chance of it staying current.

Document for Life (3, Interesting)

jafiwam (310805) | more than 7 years ago | (#17257142)

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.

twiki (1)

bano (410) | more than 7 years ago | (#17257352)

It was like pulling teeth, mainly to get my coworkers to see value in not keeping documentation in a proprietary format(ms word or visio) that is heavily version dependent, and sometimes not backwards compatible for changes stewn across several directories on a shared drive.
Unfortunately my group is the only one who uses it too, I would like to see the other groups use it.
Hell I'd even convert to M$ sharepoint over the old method, thousands of documents on a shared drive, multiple iterations, some unaccessible, different formats, not knowing which one is most current etc...

Everywhere and no-where (1)

morryveer (870752) | more than 7 years ago | (#17257376)

At previous places of employment, documentation was as follows:

1) in the "CVS" repository, coded right in the source
2) on the mainframe, under MVS
3) on the mainframe, under VM/CMS
4) on the intranet, accessible via a front-end
5) on public server #1
6) on public server #2, that for some reason isn't searchable
7) on public server #3
8) on the internet

what gets my goat the most is these "processes", which generate REEMS (reams?) of documentation. Which then are dumped onto a server and promptly forgotten about. These documents have value - if you can find them.

where's all our library scientists?

Re:Everywhere and no-where (1)

morryveer (870752) | more than 7 years ago | (#17257730)

forgot some:

9) Lotus notes databases, scattered across servers of course
10) Postnuke used as a Wiki

there was one person I know who had an interesting approach to documentation. He documented liberally, extensively, and profusely. Indexed and backed it up. But he kept it to himself. If someone came to him with a question, he'd gladly print out the portion of the documentation they wanted, but under no circumstances would he release the entire document.

now this is counter intuitive. Most managers and companies want and strive for people to share information. But looking beyond the statements of support, the people who were the golden boys were the information hoarders. I even had a manager say "well everybody goes to him for information". And my reply was "that's because he keeps it to himself". It struck a chord with me because I was trying (and failing) to get people involved in sharing information. Setting up ways for people to disseminate their knowledge. Yet the golden boys kept getting the bonuses. Most companies are like this: those that use others knowledge gain in efficiency, yet those that share it lose efficiency because documentation is damned hard work. and rarely, if ever, is documenting rewarded (by the company).

I document everything (2, Interesting)

smooth wombat (796938) | more than 7 years ago | (#17257398)

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 (1)

skinfitz (564041) | more than 7 years ago | (#17257434)

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 managers get complacent and start thinking along the lines of they never have problems so why do we need these people. That, and admin culture does actively encourage the denigration of users, often to their face which many take offence to. If they start getting big ideas about replacing the admins whenever they get upset by it being pointed out to them just how stupid they are, for example the lady this week who emailed us to complain her email was not working, then good documentation that anyone 'brand new' could follow is a Dangerous Thing.

TPS Reports (1)

Joe The Dragon (967727) | more than 7 years ago | (#17257602)

A lot of places use them.

You don't (1)

rmc (32254) | more than 7 years ago | (#17257694)

You don't. Twice a year some good soul with good intentions comes along who observes the chaos that is your IT/Enterprise infrastructure. 'We will track all our assets in one beautiful database!' they say. 'We will finally know what is going on in our network' they say.

A project is started, a gaggle of consultants make a boatload of money, and introduce a system that is uncomfortable to use and barely meets the stated requirements. Everybody is ordered to use the system, but nobody is clearly responsible for keeping it up-to-date and nobody bothers to check on the accuracy later on.

After 6 months the system is in total disarray, but because nobody repeals the decision that it is the Official System [TM] and because it cost so much to build, it's there to stay along the other Official Systems [TM] that nobody uses. That's when the idea for the next Official System [TM] pops up.

Sounds negative? You were talking about Enterprise systems, right? This is how it works in every big company. Don't fool yourself into thinking it can change. Enterprises don't change. They slowly morph around problems to avoid them, not to solve them.

The solution? Do it locally. Figure out a convenient way to track the IP address subnet assignments in your network, and use it to keep track of your address space. Use an Excel sheet for all I care to keep track of firewall rules. Use domain-specific tools, and use them only for that domain. Avoid the temptation to create the Universal Solution To All Problems because it won't work. Down that path lies agony and depression, not only for you, but for everybody else.

No, I'm not bitter, why do you ask?

I'm loving DokuWiki (1, Informative)

Anonymous Coward | more than 7 years ago | (#17259256)

DokuWiki (http://wiki.splitbrain.org/wiki:dokuwiki) is a great little wiki system and an absolute snap to get set up and rolling. I rather like its use of namespaces (logical subdivisions of content based:on:seperating:colons) and the ability to restrict specific user/group permissions based on namespace. This makes it fairly straightforward to set up a tiered access system, where senior techs can access more sensitive data that the tier 1 guys don't need to see.

Mind you, it's not meant to be a content management system; when referencing documents, we just point it to a shared drive/folder on the network where the relevant related document is stored.

Custom Software (1)

dJCL (183345) | more than 7 years ago | (#17260984)

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

JC

Load More Comments
Slashdot Account

Need an Account?

Forgot your password?

Don't worry, we never post anything without your permission.

Submission Text Formatting Tips

We support a small subset of HTML, namely these tags:

  • b
  • i
  • p
  • br
  • a
  • ol
  • ul
  • li
  • dl
  • dt
  • dd
  • em
  • strong
  • tt
  • blockquote
  • div
  • quote
  • ecode

"ecode" can be used for code snippets, for example:

<ecode>    while(1) { do_something(); } </ecode>
Create a Slashdot Account

Loading...