Slashdot Mirror
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?"
... we don't.
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!
Word+visio.
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.
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.
c al-Manual/dp/0671704273
:)
Amazon has it for $25 here:
http://www.amazon.com/Star-Trek-Generation-Techni
Enjoy
I was going to recommend Adobe FrameMaker, but that's for a different value of 'Enterprise Documentation'.
....What documentation?
- 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 will be a piece of cake.init 11 - for when you need that edge.
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.
We used to have a Bill of Rights. Now, with the rights gone, all we have left is the bill.
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
"Most people in the U.S. wouldn't know they live in a tyrannical state if it walked up and grabbed their junk." - MyFirs
Livelink by Open Text is simply the best solution on the market for ECM.
document NOTHING.
every day http://en.wikipedia.org/wiki/Special:Random
We use Confluence, a wiki from Atlassian. It also integrates well with Jira, 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.
Trac is what we use for network, backup and project-documentation. And bugtracking. And for browsing through our projects' code. "It just works (tm)".
This sig is intentionally left blank
I am just looking it up at wery fine book u can buy here.
Will code for new sig.
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 but have not had much luck so far.
Laborare Est Orare
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.
We've setup an internal Wiki site using the MediaWiki software.
Check out my sysadmin blog!
make sure you are consistent with the industry...
http://www.ratemynetworkdiagram.com/
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.
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.
(S(SKK)(SKK))(S(SKK)(SKK))
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.
Deleted
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.
Caution: Do not stare into laser with remaining eye.
If you're just looking for a business-grade Wiki, TWiki ( http://www.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/
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.
The problem with the rat race is, even if you win, you're still a rat!
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.
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!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.
what is this... earth documentation?
"You can drive out Nature with a pitchfork, but It always comes roaring back again." - Tom Waits
While not specifically for the uses stated in the article, we use MediaWiki for all our documentation nowadays. This has replaced the dreadful Lotus Notes as our documentation management system.
Put everything in the one folder and name the documents a##### where # stands for 0-9 - a true story.
davecb5620@gmail.com
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.
/still/ a wiki) formatting and complete information.
/much/ simpler task - which means there's a better chance of it staying current.
These notes become source material for the "real" Wiki entries that have all the nice (well - it's
I've also used Forrest + Openoffice.org successfully in the past. Forrest accepts OOo XML as an input format. As long as you use the styles in the sample doc from the 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
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.
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...
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?
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.
We will bankrupt ourselves in the vain search for absolute security. -- Dwight D. Eisenhower
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.
A lot of places use them.
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?
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.
For you I'd recommend a digital repository like Dspace.
"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.
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.
XMLMind ships a sorta wysiwyg DocBook editor: http://www.xmlmind.com/xmleditor/
/little/ bit, like working with tags, and work for an educational institution, (http://www.oxygenxml.com) might
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
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.
For anything beyond that, company wiki sometimes linking to files on the fileshare.
JC
On Arrakis: early worm gets the bird. Magister mundi sum!
http://www.80-20.com/products/document_records_man agement.asp
Its very much enterprise level.
The inane comments here make my wonder if any of you have a job at all.
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.
If "disco" means "I learn" in Latin, does "discothèque" mean "I learn technology"?
It sounds like many of the people here need Configuration Management and just don't know it yet. I don't know what the Windows tools are, but for Unix-based systems, you want to be searching for tools like cfengine and puppet. The basic idea is that the entire configuration for your network is stored in a central place, and distributed from there.
The nice thing about the tools I mentioned (I've only used cfengine, but puppet looks like it has better features, and I'm told it has this one too) is that they can be added on to existing systems, and different parts of the system can be moved into configuration management at different times.
These configuration files all allow comments, so you can do your documentation in a "literate programming" fashion.
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:
Now the above could use the same tools today but a little modernization is in order. Pick a Wiki, pick a common version control system and perhaps Slashdot code for discussions -- and make the policies. More importantly, vigorously enforce the policies.
Be prepared, depending on your organizations discipline, expect 10% or more to quit or be fired. Many people are solo cowboys and will not document and participate. Take the most critical of progress and ask them to leave. Take the best of those that participate and send them on a week long course of their choice.
Like Slashdot, using a online discussion mechanism discouraged dysfunctional politics. After all, the CEO might read it. Better yet, if you were new you just pulled a list and subscribed to what was of interest skipping what was of no concern, often seeing history on a application or hardware going back years in one well known place for quick background on the reasons.
Enforcement was easy during budget time, no news group with online docs, no money.
Less phone calls too, operations often had the change in the groups and got the right support more often... was good to have worked there.
Software Licensing: Document through small scraps of paper, scattered across disparate IT Departments. Supplement with 5 year old emails that hints of 30 licenses for x.
Passwords: Use 20 character alphanumerics written by hand with the command to shred them after use. Have inconsistency across platforms, and no common theme or strategy. There should be no way to find passwords if the wrong person is out of the office.
Legacy Support: Oral tradition (you need to talk to y, who implemented this system 5 years ago (and has not touched it since)).
Standard Support: Use the handy documentation located at V:\departments\it\it department\support\network applications\documentation\internal documentation\products\applications\Windows\produc ts\new\ANDY'S FOLDER - DO NOT USE\readme.doc. "Oh, that may be several iterations old - can you update it while you're your done fixing that problem?"
Network Diagrams: See whiteboard in conference room. If you need to see it while in the field, ask someone to take a picture and send it to you.
Data drops: Labels take to long. Use a toner.
Broken ports and switches: Plug it in. Does it work? Then it's broken.
Organization / job title chart: Why would we need one of those?
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 a sealed, signed envelope...