Slashdot Mirror
How Do You Document Technical Procedures?
ChadDa3mon writes "I work for a large MSSP type operation and we deal with a plethora of vendors, versions, and .... skill sets. We're facing a critical problem as we grow when trying to deal with these varying degrees of technical competency. The end result is we're getting to the point where we have to document every procedure and process, no matter how mundane or 'common sense' it may seem." How, ChadDa3mon wants to know, can complex skills be documented to account for various users? Read on for more details of what he's seeking.
"I've got a picture of how I'd like this to work in my head, but I can't find any software out there that seems to go along with it. I'm a big fan of keeping things simple, so I'd like to start with high level overviews. Each step in the process would be a general statement like 'Look for valid traffic on the monitoring interface'. For those who already know what 'valid traffic' means, it's easy to follow. However, if there was someone who was unsure what it meant, there would be a link they could click on that would pop open a new window (or something similar) explaining in detail what we're looking for and how to find it. It's my hope that using this process, people aren't just blindly running commands, but gaining an understanding into what that command is, and why we use it, what to be aware of, etc.
This seems like a job for a flow chart, but I don't like the setup of any of the ones I've used, such as Visio. It could also maybe fulfilled by a wiki, but there's so many out there I don't know where to start. I have to assume I'm not the only person who's facing a problem like this, so I'm hoping someone else out there can make some recommendations."
This seems like a job for a flow chart, but I don't like the setup of any of the ones I've used, such as Visio. It could also maybe fulfilled by a wiki, but there's so many out there I don't know where to start. I have to assume I'm not the only person who's facing a problem like this, so I'm hoping someone else out there can make some recommendations."
Documenting technical procedures is bad for job security.
I just use a text document with point-for-point descritions on how to follow the procedure. It's practical because you can print it and take it to the workfloor and cross the points you've finished. When you find out something new you can easily write it on the paper and add it in the computer file later on. Just make sure there is only one person maintaining the file, to avoid chaos and misunderstandings.
-- Cheers!
If there's a mistake or something in your docs are unclear, you want the guy using the docs to be able to fix it right on the spot. For that reason use a wiki, no-one is going to fire up Visio or whatever and diddle a flow char tin the middle of a call.
I assume the people using it are phone monkeys, make sure to track who makes improvements so that it doesn't penalize the guy who takes a minute to fix something but then their talk time suffers and they get bitched at.
I was reading through some of the Trac hacks for the wiki component and they had a folding plugin. If you create a table of steps you could then create a "fold" with greater detail should someone want to open it up and see it. The nice thing is you are not taken to a new page and you can continue to work and read the page you are already on. You can also imbed folds which can also allow a user to drill down to as much or as little detail as is needed or available.
All that is left now is to write enough information for the lowest common denominator.
---- Fight to protect your right to keep and arm bears! ummmm... ya I think that's right....
...I usually start with documenting the configuration on a Wiki (or a file in a Subversion repository somewhere) and then shift things over to Puppet when I get the chance. The nice thing about the latter is that you know all the setup specifications are correct since that's what's actually being applied to the servers.
Documentation of system provisioning is just one small part of the question you're asking, but hopefully that helps.
The Army reading list
That's what we call it. We write up a set of directions so simple even a monkey could follow. We include screen shots at just about every step so the user can see what it looks like. Currently we have them in a mass collection of Word documents spread over a bunch of network drives. Yea, it sucks to find a particular direction document.
We are in the process of loading all of our monkey directions into a wiki. That may work for you. You could create pages that have the high level overview directions for the users that know what is what and then have each direction link off to another wiki page that has more detail.
No matter what direction or option you find one thing you need to keep in mind is the more simplistic you make your directions the harder it is to keep them up to date.
Whatever you do, make sure the process for creating and updating the documents is simple, or it'll quickly become out of date and useless.
I would recommend NOT using any special software like a wiki for your primary documentation. It should be simple and printable, and not need a special server set up to access/use your docs in case of a disaster recovery situation.
Create a template document. If you use a word processor, set up standard formatting styles for sections, TOC, etc, so the docs are easy to create and navigate.
Put enough detail in the document so that you can hand it to a marketing droid and have them successfully complete the procedure. You'll be glad you did when you're stressed and under pressure from the Big Boss in an emergency (or if the whole IT department keels over from a tainted batch of Mt. Dew, and the only people left are completely unfamiliar with your environment).
As an IT consultant, my approach to technical documentation is to document the specific configuration of a system. I specifically do not try to explain the product that I am documenting, but the configuration that I have given the product. For example, I would document the non-default installation options and the non-default configuration changes that I make after installation. Then, I will include in an appendix some links to internet articles/pages that explain generic concepts of the software product I am implementing.
In other words, I assume the reader is technically competent on the product, but needs to know how the product is configured in the specific situation.
Keep in mind, my audience is usually IT staff, so this may not be an appropriate approach for end-user type of documentation. That is more difficult, because there technical savvy cannot always be assumed. (IT staff members' technical competence cannot always be assumed, either, but IMO you cannot/shouldn't try to "teach" them a product through situation-specific documentation.
Looks like an obvious use for a Work Flow Diagram- you can do it in Visio as a flow chart with "page links", but then the user would have to have Visio to actually read the document. I suspect it could be done in HTML also.
SJW: a person who perceives an injustice, and while correcting it, commits a greater injustice.
a consistent quality between my documentation of technical procedures and my source code.
That's always the catch, isn't it? I'm sure we've all seen the printed instructions with more handwritten addendums and notes in the margins then there is printed text.
Proud member of the American Non Sequitur Society. We might not make much sense, but boy do we love pizza!
What's wrong with documenting your procedures using...... a *document*? Okay, get fancy and make it an *HTML* document.
If you want to use a wiki, I've been happy with dokuwiki.
but I can be bought.
You need a competent process engineer, and good ones are expensive. Bad ones are a dime a dozen, and will drive your costs up by insisting, for example, that every procedure be a documented procedure, that every process needs to be flowcharted, that there's a distinction between a process and the document describing the process, or that the fiction that is RACI is not reducible to a single directive: "accountable".
This is, as they say, job security for the process engineers because they're constantly chasing a moving target. Also, the instant employees realize or suspect that they're being made interchangeable by participating in any process engineering effort, they'll learn to conceal key details which will make all work to date useless.
Organizations that don't realize that have chosen the way of pain. Yours is probably one of them.
Slashdot is my Mercer Box.
Use your favorite text editor or word processor and document every mouse click and/or keystroke. Using script to record a command-line session (when available) to use as a basis for your document can be a huge time-saver.
I have to second this. Having done an honest job of trying to leave good foot prints behind, and having to follow the footsteps of someone who follows the GP's philosophy, I submit that the GP and their ilk should be put aboard the Lawyers, Actors and Politicians shuttle and launched into space.
Are these documents actually intended to be followed and how technical do you want to get exactly? Who's going to follow them? Why would they want to?
Because if the answer is "we'd like to be able (in theory at least) to hand over all network troubleshooting to the marketing department" and you have a complicated network, your documentation is going to include a reprint of an entire CCNA course - and possibly the CCNE as well.
The solution we use is a wiki and a few rules of thumb - such as "if your procedure is more than a page or two long including screenshots or diagrams, it's too complicated to expect someone to reliably follow it. Make it simpler (with scripting and automation if necessary) and document the simple procedure".
Speaking as someone who has a degree in technical writing, your question is symptomatic of the entire industry's attitude toward (read: lack of respect for) technical writing. You hire people with degrees to run your networks and program your computers and execute your business processes, so why are you not hiring someone with a degree to do your technical writing? It's a specific skill that most people do not have and those who do it have had to study and learn. Realize that and you'll be better off. [/rant]
"We can categorically state we have not released man-eating badgers into the area." - UK military spokesman, July 2007
I can't stress this enough. There are professionals who have post-graduate education and vast experience documenting and communicating technical procedures. Hire one of these people.
If you don't hire a technical writer you will face all kinds of problems. You'll have technical people with poor English skills writing incomplete directions because they make assumptions about what the reader knows. You'll have 50 manuals with 50 different writing styles. You'll have 10 instructions in one sentence with no commas. You'll have unfortunate typos and grammatical errors which change the meaning of the sentence.
Technical writers are both technical and writers. Hire one (and not the cheapest one you can find) to do the job right and chock the expense up to preventive maintenance. The alternatives are putting faith in poor documentation and, in the best case, spending needless cycles working out the kinks, or, in the worst case, spending needless money on a settlement to your injured customers because your staff were improperly trained.
If you don't know where to start, start somewhere! First, decide upon the generic interface. It sounds like you want it to be web based, so that's prolly covered. Next, just find a bunch of Wikis - ask your IT department or Dev department if they're already using one - and start working in them. Read the documentation for each wiki, making note of the features you like, and try those features out. Decide which one fulfills your needs the best, and use it.
As for those idiots who say that documenting what you do is bad for job security: if you're relying on it being difficult to replace you with a pigeon, then you're not bringing too much to the job and maybe this is true. On the other hand, if you bring experience, a good attitude, adaptability, ability to play well with others, domain knowledge, ability to apply that knowledge to reality, etc. then you are hard to replace. Where I work, the ability to communicate what I do is very helpful. I'll leave certain tasks for years, after which I'll have to pick them up again. If I haven't taken good notes, documenting how to perform those tasks, I'd have to relearn them all over again, which would be a net LOSS for the company, making me LESS valuable by wasting resources, and making it MORE likely I'll get fired, not less.
Choose any goddamn thing to start documenting (I use MediaWiki, since everybody seems to have some experience with Wikipedia nowadays, so it's not so jarring). Job swapping is essential, since you'll never know how good your doco is until you test it. Choose the best communicator with skillset A, the best communicator with skillset B, and let A do B's job with B watching over, documenting all the way. Swap and repeat. Do the same thing with all other combinations of skillsets you've got. Then test again: when A takes a day off, find a B to replace him/her as a stand-in. See how well he does. If it's not tested, it's useless.
For simple procedures, I just use Powerpoint, and have extra, separate graphs when a particular task can be expanded to a subgraph.
If anybody has any other graph packages to recommend, I would really appreciate upgrading.
First off, you mention that there are varying levels of skill sets and that is reason you have to document everything. That will always happen and will not change with any half-decent sized organization, so get used to it now.
As for methods of documentation, my organization has found wikis to be very useful with process documentation. The trick to getting everybody to contribute to the wiki is making it easy to edit. I personally prefer MediaWiki's software, but a lot of people look at the text and freak out. As a result, we employed a "Word-like" document editor and people have really jumped onto the idea. It's still taking convincing of people who are used to huge Word documents that they e-mail around, but the centralized location of the wiki is slowly drawing people over the idea.
One tough sell point of the wiki is, "everybody can edit it! Oh no!" I'd recommend heading this off right away. Force everybody to log in (maybe through their Windows account) so that every change is tracked. Additionally, head this off to explain that this is a huge benefit of everybody being able to edit is that nobody needs to type a huge amount of information. Each person contributes only what he or she knows. (This is all basic wiki information, but when trying to sell a new technology to an organization, you have to really make sure you cover all the areas.)
Look up 'Knowledge Management' as a starter.
We have most procedures documented step-by-step on what we call 'one page guides' (OPGs) - in other words, if you cannot document a procedure on two sides of paper then it's too complex and needs to be broken down further.
The OPG form is a standard template in Word. having a common format ensures that people can scan through OPGs and know exactly where to look forthe details they want. The OPGs have sections as follows/EG:
TITLE: How to Reset a Draytek Router to Factory Defaults
Scope: Comms
Description/Symptoms: A router may need to be reset when....
Action/Procedure:
1.
2.
etc.
*end*
We don't use flowcharts as it takes too long to create maintain them. Simple, stepped, lists in your favourite word processor are easy to amend quickly.
We have 6 categories of OPGs (because that suits our needs: Hardware, Software, Comms etc.) and each staff member has the 'top 10' OPGs for each category in a folder on their desk for reference. We do have them online, but paper copies are easier to search through when you are not near a computer. All other OPGs are also held online and in SOP folders in the work area.
Issues such as 'Look for valid traffic on the monitoring interface' are handled exactly as you describe - by refrence to another OPG - so staff can check them out if needed.
The Knowledge Management aspect ensures every OPG has an owner responsible for its maintenance, plus there's a submission, validation and approval process. It's a bit like hard work to setup, but once you get organised, doing it properly from day-one pays dividends.
AT&ROFLMAO
Creating a policy for technical documentation is the best way to streamline procedures.
Once the staff is up to date on the policy, and templates are available, the creating procedures are easy.
It also helps when it comes to revising the procedures.
It's You and I against the World... When do we attack?
Wiki would still work for this. Most wiki's come with a printer friendly css style sheet so that printing an article looks nice and doesn't waste paper with menus et al.
In response to the first response:
Is there some kind of Wiki that does UML? Or a UML engine based on a Wiki? That'd be awesome.
----
Captcha Text of Irony: obscurer
Comment removed based on user account deletion
We used DocBook to write over 500 pages of process documentation for people to follow. After an initial learning curve with it, it was very easy to code up tagged text. Then it was convenient for it to translate into whatever format we needed, HTML, PDF, etc. That was the easy part. And I agree with other people here - keep it simple.
The hard part is getting anyone to actually read it and use it. Practically nobody did, and less so the further down the skill chain you went. What did work for us was holding regular in-service training sessions with everyone, covering one topic per week, and eventually getting everyone up to speed. We used the documentation as handouts, printing the relevant sections for them.
Learn how a CPU works before you learn to program. Seriously.
paper and PDF files cannot be "messed" with and passed on with new, incorrect, information added in (without some extra work beyond the problems in that area a wiki presents)
Remember - you are showing people how to use a product and NOT teaching them a new skill or how to do their jobs (hopefully).
It is not unexpected that your company would require some basic knowledge beyond remembering to breath in order to provide security services.
Wikis are great for this.
I hope that after I die the one word people use to describe me is "resurrected."
Ummm, we write a document?? We have tons of "Work Instruction" documents that "document" the "Instructions" for how to do "Work"
There are many skills in this area that stay the same through the technology bubble we are witnessing in information technology. When you write you need two things. 1.) Purpose 2.) Target audience.
Concentrating on Audience for this reply... a very good technique is to use a "personna" or "profile." Create a fictious person providing an age, gender, education level, personal habits and so on. You then write that that target. Of course, not everyone who reads will fit in the personna exactly, but your personna will will have a bell curve associated of applicability to other audiences. Agree on the personna with all who are contributing material.
It works almost like magic.
When documenting operating procedures for nurses to replace doctors, I found it beneficial and easier to remember if you make it sing along:
"The leg's bone's connected to the...knee bone. The knee bone's connected to the..."
I did a contract for a company with this very issue. They were hiring expensive consultants to come in and fix, undocument procedures and code. Part of the problem was some of the people doing the tasks couldnt write to save their life. So, I got out my cannon video recorder. Did some interviews and video'ed the procedure with screen close ups and questions to the user. Streamed the video to mp4, loaded them on web page, and voila! All procedures demoed and explained by the people who do them. Add some tags to each video and they become searchable.
We use MediaWiki for that purpose. MediaWiki runs WikiPedia so it isn't going anywhere and it works well. It is designed though for that massive site usage so some things are not so convenient when using it on a smaller scale in a company (and I suspect patches that would change this would not be accepted as obviously whatever WikiPedia uses must scale).
One decision before my time was to use one wiki per group. I would strongly recommend looking into namespaces or some other grouping option that will let you keep everything in one wiki. This will avoid duplication of content, having to explain interwiki linking, maintaining interwiki linking tables, maintaining templates across multiple wikis, and lastly having wiki-wide searching. Using a single wiki may not have been so easy as it is now with current versions of MediaWiki when the decision was made here but now it is certainly straight forward.
Finally, lower your administration overhead by allowing everyone to create, edit and delete. The deletions can easily be reverted so there is no need to go overboard on locking features down.
If you are mainly a Microsoft shop, SharePoint works will for posting procedures and related docs. Works pretty good for us. Is a pain to use when trying to rearrange items later, though....
You're messin' with my Zen Thing, man.....
I think the tool is the least difficult part of such an endeavor - changing culture is difficult.
Documentation is critical to business success, no matter what the business. The reality is not about "protecting" your job or keeping the PHB's from mucking with things. The reality is that it may not be what you do, but what the other guy has in his head that is critical information for your business.
In other words, what happens when a critical employee has a heart attack, or gets hit by a bus. What do you do then? If everyone has their little piece in their head, no one else benefits, and the business overall loses. Or, even more simply, what happens when someone goes on vacation? Or when you go on vacation? Do you (or does the business) suffer because there isn't a way to replicate what that person does?
In this day and age, business processes are perhaps the most valuable thing a business owns. Knowledge can be learned, information can be looked up. But utilizing information in a business is *NOT* as simple as having that information. How information is applied to the business is the key. And documenting that information is the *ONLY* way to get it out of someone's head and into the general domain.
I've had this discussion recently both as part of my business (an IT Services vendor) and as part of my customers businesses. In every case the answer is the same. The processes are the most valuable asset for any company, no matter what the size or business. In fact, the smaller the business, the more valuable, because the likelihood is that in a smaller company there are more concentrations of knowledge, more key people who, if hit by the hypothetical bus, would take with them the day to day processes that run that business.
There are many ways to approach the problem. From embedding processes into a help desk program, to external solutions such as Wiki's, to professional programs that are specifically designed to collect knowledge, flowchart it, and also align it to your business processes.
One of the products that my company handles is specifically designed for this: aligning IT processes to business processes. While this is generally a new concept, and a tough sell, when you can map out what you do in your IT department, and also see the business reasons for why you do it, not to mention see the business impact if you don't do it, the value can be staggering. This is one of the greatest untapped barriers to IT becoming part of the larger business, and demonstrating its value. Far too often IT does things because they need doing, but they don't understand how what they do affects the business, or what value their day-to-day activities actually have in the larger business. And the reverse holds true as well: the business doesn't understand how their needs and requests impact IT, or why they cannot simply "make a wish" and have things their way.
Control of your business processes is the single best way to ensure that IT is doing things the right way for the business, and to clearly demonstrate the value (monetary and otherwise) of their jobs to the PHB's and accountants and other ickey people on the business side.
Documenting processes might be the best way to protect yourself, and save yourself grief. Its only a very narrow and stupid point of view that sees this as being a way to protect themselves, and make themselves "valuable" to the business.
Bill
"we deal with a plethora of vendors, versions, and .... skill sets....trying to deal with these varying degrees of technical competency..."
Translation: how can the total idiots where this guy works be equipped to do something productive?
Answer: they can't, they're idiots! They will screw it up, documentation or not. Put them on something harmless and far away from anything important if they must remain on the dole.
...There is documentation. One of the most important things in dealing as a large company is to work in making sure everyone can get accurate information everyone needs. One of the most daunting tasks is sorting and maintaining this information as everyone has different levels of proficiency... so, in truth having several different copies of the same documentation geared towards different aspects of the business is very helpful.
How does one explain an OC-192 line from a Marketing perspective? How does one explain QoS routing to Level 1 tech support? How does one explain FCC rules to Sales People and still make that information understandable by customers who have a rough time programming their VCR? These are issues faced in putting together a documentation project for a corporation. Less is never more for documentation and targeted, simplified versions of highly detailed technical procedures are also valuable...
The trick is putting together a system that does all of this and is easy to update everything that needs updating.
I can't give you any advice on how to document your procedures for your company. However, I have some experience in managing documents. Dead tree doesn't work. Very soon (and especially in the beginning of documentation process) you will run into problems with keeping everyone on the same version of documents. I looked into various open source CMSs based on wikis and other engines and decided to deploy alfresco in the end. Alfresco does everything my company needs: it can keep different revisions and translations of documents with ease, has a simple but functional access control system and an easy way to start workflows and discussions on documents. It also has interfaces for web publishing, network drives, wikis etc. The free version is a bit hard to deploy right but once deployed it is trouble free.
Gentlemen, you can't fight in here, this is the War Room!
I think you first need to figure out whether what you want is for everyone to follow a certain procedure (bio labs have set protocols) or just to have a record of what work people have done (like lab notebooks). Here are some brief (and incomplete) thoughts:
Protocols, pro:
- high consistency, as long as people actually follow them
- can be easily edited and everyone will be able to follow the improvements
Protocols, con:
- little flexibility, depending on how they're written
Lab notebooks, pro:
- allows flexibility for all situations, allows for worker's ingenuity
- accurate record for worker's actions, as long as they write it down
Lab notebooks, con:
- no consistency from person to person
- no structure or prompts for person to follow
"Two things are infinite: the universe and human stupidity, and I'm not sure about the former." -- Albert Einstein
Mind mapping software is brilliant for that kind of stuff.
FreeMind is a good start. Start with the overview nodes, then add sub-nodes for a bit more detail, then you can add sub nodes to them again, until you're into step by step commands to run.
It is free (GPL), runs on most platforms (Java), can export to html, and is really easy to work with. Saved files are in xml format, and there's even flash / java widgets to read and display the files directly in the web browser.
Here is an example java viewer, showcasing some of the functions of freemind (and being documentation for the java applet)
It's The Golden Rule: "He who has the gold makes the rules."
I started doing a little software development for my company (when I was hired to do help desk), and I was once asked to write a procedure for that. How do you write code. I replied -- Step 1) Go to college for 4 years and get a computer science degree.
I'm in the middle of this same process. I'm using Drupal along with the CCK (http://drupal.org/project/cck) and Views (http://drupal.org/project/views) modules to accomplish this. If you aren't aware of what Drupal (or CCK/Views) is, then please take a look at: http://www.drupal.org./
Basically, Drupal is a CMS application. CCK allows you to create custom content types for Drupal, thus allowing you to further control the structure of the content that is placed inside of Drupal. I'm using CCK to capture: Objectives, task lists, dependencies, team members etc. for each procedure. Views allows you to display the captured data in various ways. It allows me to generate listings of all of the procedures etc. and they are sortable.
You'd be surprised at how simple this is within Drupal. Give it a look...
It's that simple. Get an internal Wiki up and running immediately, and encourage your team to dump every single little bit of knowledge into it. It won't become a complete repository overnight; it takes time, but as more information flows into it, it will become more and more useful.
Also be sure that your wiki has a full text index so it's easily searchable. This is actually more important than building pages that house tables of contents.
Tired of FB/Google censorship? Visit UNCENSORED!
When users don't know what a term means they can find out and create a link in the wiki to the explanation page. It works where I work (when people remember to use it)
It really doesn't matter what you decide to use. Wiki, Sharepoint, a file share with a bunch of Word docs. It doesn't matter. Just get things written down.
Now, that being said, I tend to mix procedure docs with configuration docs. You can try to keep those seperate but it's often easier to combine the two. So, say you have a thin client system set up, you can have one doc that documents how the system is configured and how to perform basic tasks.
You don't need to get too detailed, of course. The intended audience isn't a non-technical user. Each document should have a few basic sections; Revision history, purpose, intended audience, and a simple explaination of terms such as for certian acronyms used. It's also useful to include software versions so you know what version of the software the document was written for. As you upgrade the softwasre, update the doc and update the software version.
Create a document template and with pre-formatted styles. That way, you cab bust out organized documents that all look the same and every one will automatically get things like a TOC based on your styles. It's worth putting in effort here.
In the end, though, just get as much information as possible down on "paper" and then work on making it accessable. I'd rather have to hunt for that IP address or login to a web site than to not have it at all.
And remember, it's not your job to provide TRAINING materials to people in the form of this documentation. (unless it IS your job, but it doesn't sound like it.) Your job is to make sure that the systems stay running and if something should happen to you, the company isn't screwed because the systems are documented. Perhaps more importantly, if a server you worked on a year ago crashes, you'll have all the information you need to fix it.
Anyone that thinks Documentation might lead to their dismissal because "We don't need him anymore" is dead wrong. If you write documentation, you'll be the most loved person in all of IT in your company.
- It's not the Macs I hate. It's Digg users. -
MediaWiki for all the text-only stuff. Use the Graphviz extension for nice flowcharts (not necessarily pretty flowcharts - use Visio for that).
Flowcharts of method but scripts are really bad.
A great example of this the "help" line for an oversized ISP. You get asked a load of irellevant questions because that is what the script says - even though you told the operative precisely what the problem is. They have to follow the over-documented step by step procedure.
Example
Customer Hello? I need a new HDD. I got errors X, Y and Z so I ran your boot CD and it did a BIOS test and said error 7 so please send one.
Helpdesk Please check the following... (for 5 minutes)
Helpdesk Right, so the drive is there and we have errors X, Y and Z. Have you tried reinstalling Windows?
Customer No, the error indicates a hardware failure(5 more minutes>
Helpdesk Do you have our system CD? Please put it in the drive...(10 minutes to run test)
Helpdesk I see you have error 7. This means you will need a new HDD
It is not the fault of the helpdesk that they ignored everything you told them at the start. They are required to. We all know that end users have varying abilities and intelligence. That is where Staff training can save a lot of company time and improve customer perceptions.
I'll see your Constitution and raise you a Queen.
tiddlywiki might be a nice possibility. I like the way it expands sections. easy to lock down. easy portability that anyone can read (only web browser with javascript needed.)
When Jenny Greene and I were working on Applied Software Project Management, we put a lot of effort into coming up with a way to document the practices that we wrote about. We wanted to make them really easy to understand, because we didn't people to have to learn to read something heavyweight or cumbersome.
We ended up using "scripts" (think scripts that an actor uses, not scripts that a shell script uses) that just explain each process or practice step by step. We got a lot of mileage out of adapting the format that we used for use cases -- you can see an example here -- it's a pretty standard way of writing down use cases, but we'd never seen it used for practices. But it actually ended up making a lot of sense.
That format worked really well for us: we used it for estimation (using Wideband Delphi), inspections and code reviews, developing specs, planning for risks, and a bunch of other practices. You might get some mileage out of it too.
Building Better Software
I've done this before... what you really need are two separate documents. (Yes, they are a pain to maintain.)
First, you need a "training" document. This is the one with pretty screenshots and terminal logs going over the procedure in excruciating detail, and this document is used to train new folk on your setup. This is mostly utilized as a guide for...
The second one, which is more of a shorthand checklist template. (Few experienced admins will wade through some lengthy "admin for dummies" procedure after he/she has done it a few times.) This document has the information for the change ticket buried inside the checklist, which increases the probability the checklist will actually be used.
Here's a trivial checklist sample of changing directory permissions:
Wrong /foo/bar
User: John
Dir to be added:
Server Hostname: FooServ
Permissions to be set: 345
Charge Code: 3456
Change Request Number: 12345
1) Login to server under admin acct.
2) Set appropriate dir permissions.
3) Update accounting database with charging info.
4) Update chg control db with new permissions info.
5) File TPS report of completed change to PHB.
Sign Here:____________
With a checklist like that, the boring crap after the change is done oftentimes gets skipped because the admin just makes the changes to the server, gets distracted while doing housekeeping, and just signs off the ticket.
Right:
Initials:
____ 1) Login to Server __FooServ__ under admin acct.
____ 2) Set the permissions in dir __/foo/bar__ to __345__
____ 3) Update the accounting database using charge code __3456__
____ 4) Update the change request number __12345__
____ 5) File TPS report to PHB
Okay, that last one will still get skipped...
Anyway, that 2nd checklist forces the admin to actually make some effort at reading the checklist instead of just using the header info, and possibly skipping steps.
SirWired
With windows you have to capture a screenshot, point out which button to click on, whether it needs a double-click, right-click or dragging anything. Then you have to go through the whole process again for the next level of window/menu.
No wonder graphics based O?s's (or those with graphical front-ends) are so poorly understood and even more poorly administered - no-one has the time to create these bulky and sparse documents and they have even less time to update them when a new release comes out and changes everything.
politicians are like babies' nappies: they should both be changed regularly and for the same reasons
Writing is half the battle, maybe less. Keeping the docs current and useful is the real issue.
Every time a new guy goes through a procedure for the first time (or first couple of times), hand him the docs and have an old guy watch over his shoulder. When the new guy hesitates or gets stuck, update the docs. When the old guy says "no no, we do it differently now", update the docs. Some will say you're using two people to do the work of one. But you're actually doing three things: Training, maintaining the docs, and executing the procedure. Four if you count "team-building".
Maybe goes without saying, but whatever format you choose for your docs, it needs to be version-controlled.
Walk the end user's chosen representative (the lead member of your operations team, whoever it is) through the process but have them actually write the document with your guidance and send it back to you for approval / comment. The problem, in my experience, is not so much any lack of documentation but the lack of documentation that gets read and understood.
Nullius in verba
And simplistic language at that. The more common language you use, the better. use italics for technical details like paths, code, and commands.
And don't forget the explain your conventions at the beginning of the docs.
They're using their grammar skills there.
Postits Everywhere.
What's in a sig?
The biggest problem with procedure documentation is the "why" is often left out.
OK, so I need to 'Look for valid traffic on the monitoring interface'. Why? What is the point?
This really helps when technology changes but the core requirements and especially the tech docs haven't. If you know why you're trying to do something you can find new ways to do it. But if all you ever learn is "Click File, then click print, then click OK" you'll only get what you're trying to avoid.
obviously no deficiencies vs. no obvious deficiencies
The obvious way is Business Process Management (BPM), such as implemented by ProcessMaker and Microsoft's Sharepoint.
I'm really surprised this stuff hasn't caught on more; it's perfect for managing processes in open source teams, like how to file bug reports, or how to install some plugin.
One of my project managers has been using TIBCO Business Studio. It allows nested/linked flow-charts like you were describing and he apparently likes it much better than Visio. It is a free "lite" version of some of their other software. I've (fortunately) never had to do anything like that myself so I can only give second hand advice.
From a user perspective, both our lab techs and engineers have no problems using them. I think that nested flow charts work well on screen, but are not necessarily ideal for printed documentation.
Whoever modded this troll is an idiot. The parent has a very good point (albeit said elsewhere too). How many coders who document their own stuff know about information design, for instance?
it allows processes to be defined, reviewed, refined and documented
How do you think I've kept my job for so long?
What?
I'm sorry, I'm not familiar with that term.
"I use a Mac because I'm just better than you are."
Some people will say that checklists begin to break down when there are too many tasks that are too complex. I guess you can reach that point, but I haven't seen it yet.
I once worked on a deployment that took a group of grumpy field investigators and completely changed everything they did. The centerpiece was giving them each a computer (first computer most of them had ever touched) with an application designed to automate their paperwork. Around that, we changed everything else - new location, new furniture, new work processes - all at the same time. The highest potential seemed to be for total disaster.
Then we got *the* checklist. Starting two years before the go live date, the list took us from step to step to step, thousands of them, in order. The thing was a completely incomprehensible jumble if you tried to take it all in at one time but if you just concentrated on finishing step 555, then doing step 556, then step 557, the entire thing got cut into manageable little tasks that everyone could wrap their head around.
The result was a rousing success, far greater than any project I've worked on before or since. Lockheed Martin was the primary contractor. I've often thought those guys should go into some other business where their organizational skills could be put to good use completing mind-bogglingly complex tasks like, oh, I dunno, building military aircraft or something.
In case you can't tell, I'm a real fan of checklists.
Include lots of those.
Seriously.
I have to write documents that actually show which checkboxes are selected in the screenshot.
I wish I was kidding.
They have the tools to extract the knowledge you are talking about and documenting it. It really is a specialized type skill. That doesn't mean that you could not wing it yourself and do a fine job.
Must be some kind of new-fangled term out there....haven't heard it or seen it really much out in the work place...
Seriously, I actually have RARELY seen it in the tech end of things. On projects I'm on, you have those people doing risks, and other paper pusher jobs doing all kinds of documentation, but, I rarely see much of any kind of good documentation in the tech end of things. I'm talking big projects, govt. projects...etc.
For instance now, working on a gig to take over a number of database instances....I didn't even really get a list of what databases instances are even OUT in the environment, much less how each was set up, etc. Hell, took me weeks to find someone who had the oracle OS user password.
I'm currently documenting stuff, but, I don't find it that unusual to come into a job, and in the tech area actually have very little documents and procedures. I always hear about people out there going through and heavily documenting things and processes, like naming standards....but, very rarely have seen it in real life practice.
Light travels faster than sound. This is why some people appear bright until you hear them speak.........
Traditionally, we have always documented technical procedures by telling stories around a campfire late at night. Some younger IT people have suggested putting up Wiki pages in a well-known location that all employees are urged to keep current, but I for one just can't get used to these new-fangled ideas. (Printed documentation is invariably obsolete. Wiki pages should be updated whenever procedures are changed, as soon as procedures are changed.)
I've abandoned my search for truth; now I'm just looking for some useful delusions.
Keep the procedures in the head, where they're safe from prosecutors.
Actually, if your workplace is ISO certified, it would have had to document procedures and work instructions to get and maintain the certification. A procedure contains high level information, while a work instruction actually documents what steps it takes to do the job. The one thing ISO does is force (theoretically) a company to do what they say they are supposed to be doing, the other thing is does is generate tons of documentation. It just goes with the territory if you want the cert.
"I've got a picture of how I'd like this to work in my head, but I can't find any software out there that seems to go along with it. I'm a big fan of keeping things simple, so I'd like to start with high level overviews. Each step in the process would be a general statement like 'Look for valid traffic on the monitoring interface'. For those who already know what 'valid traffic' means, it's easy to follow. However, if there was someone who was unsure what it meant, there would be a link they could click on that would pop open a new window (or something similar) explaining in detail what we're looking for and how to find it.
What you do is start a local, specialized verion of Wikipeadia. So if you are hire to shoot squirrels you can read the general overview what it says "Aim your gun at a squirrel then shoot it" but if you click on "gun" to lland of the artical where it explains about a tube that shoots from one and and how to not point the shooting end at anything you don't want dead.
The nice thing about Wiki is that (1) The software is free and everyone knows how to use it and (2) your documents cn grow over time and stay up to date.
That said my bosses still like paper documents. They like a nice neat product that can be called "complete" and get approval signatures on it. But then I ask "have you ever seen anyone READ one of those documents?" It's a generational thing. But I really do thing a living hyper linked document is the only why to go. If you have control issue then you need some kind of revision control system hooked up to the Wiki. Those are available and not hard to use. You can have a working wiki and periodically turn over the "approved" version controlled Wiki to the public if you like to work that way.
check out rational process builder - it allows processes to be defined, reviewed, refined and documented
At my 12-person (and 70-client) internal web consulting shop, we use the heck out of Trac's wiki. Here are some examples.
If your company has itself a nice neat little network you can build yourself an intranet wiki to document all code and procedures. I've done something similar with my business and it helps with a lot of things!
It allows for easy access to business requirements by the tech leads as well as detailed explanations of function for the business leads. It will take an effort to set up, but once its going you're golden!
1. You go to engineering or science college
2. You work as a young engineer/scientist and
learn from the war-horse engineer/scientists
3. You don't start a company with no clue and no skill
Then you can document your process if you
really need to.
Grow up. Take your venture money and crawl away.
Don't document mundane tasks. Instead, automate those tasks so that humans don't have to do them. If you have a long scripted process for performing a task, script it. Then, document things in two ways:
1. High level documentation explaining the process, and what scripts to run or automation to utilize to perform the task.
2. Write well-documented code so that if something goes wrong, the operator can see what happened and how to fix it.
We use a variety of techniques and technologies to write documentation internally, but it's all web-accessible, and every project/team has a home page that has all of these documents linked from it. We don't document the mundane, unless it's something that someone must think very hard about before they hit enter.
i just take a picture of one of the server admins sleeping nude next to one of the server stacks and scribble in crayon: find this guy
[an error occurred while processing this sig]
At the last 3 jobs I worked at I helped introduce Mediawiki + LAMP server for departments looking to document procedure and products.
My attitude with documentation was the following:
1) Never assume your reader knows all the steps. Include all details.
2) Create a single article for every single thing, procedure, network element, piece of equipment, department, person, etc. NEVER put multiple entries on one article.
3) If the steps seem too mundane or common to you, then consider creating a seperate article for those steps and refer to that in the other article you are writing.
Departmental wikis are as effective as you make them. Ours tended to be very fast, accurate and did away with the old fashioned M&P meetings and Visio chart hell we had previously.
"In other words, when you say "we have to document every procedure and process, no matter how mundane or 'common sense' it may seem," you've already lost. You don't need meticulously documented procedures, you need to take those "varying degrees of technical competency" and educate them to a higher level of competency."
I think you may have been approaching it wrong. Don't think about writing out steps 1-10 on every task to make everyone's job scripted. Just lay out the steps for the most common tasks, and then document all the information you can in the Wiki so that when your readers get to that jumping off point they have all the detailed information they need to put the pieces together themselves.
We've started a similar knowledge base project, and after a lot of searching and testing, we settled on Atlassian Confluence as our Wiki.
It has some excellent plug-ins, so our Visio diagrams can be displayed as web pages. The individual pages can be locked down at a granular level. It has a Sharepoint connector to tie in to our Sharepoint Intranet system.
I've directed my team to post two new articles per week, and the Wiki is getting populated quickly. When a job that only gets run every quarter comes along, we get the steps documented. Our internal processes are on flowcharts so the business folks can see what happens when they put in a request. It's been a very helpful tool, and has not had any down time. We even have embedded Spark messaging links by all the user names, so you can contact an author to ask a question.
"First things first, but not necessarily in that order."
- Doctor Who
"I work for a large MSSP type operation "
so YOU work for a large $$$ company...
and you want OUR advise?? OUR expertise, OUR consulting... for free???
Come on people, we shoud be getting paid for this. Why hasn't slashdot come up with a system that pays for the best answer. Its a win win... companies sign up, they get access to the most talented community... they get their answers, we get the money, everyone's happy and slashdot gets to keep a small fee.
As some others have stated, it is best to find someone in the field to document rather than having someone who really has no clue. If readers can't understand your document that's only 5% of the problem. The other 95% is because the author. I know many people "think" they can write but in reality they can't. Even wiki articles are a joke sometimes because it has no structure and flow. I've seen, met, and know many experience professionals in various fields that very knowledgeable but they can't put it on paper for the user to understand. It's not a simple thing to be able to write for a targeted audience. Most, if not all, of the technical websites are poorly written articles and reviews. Often times you wonder who the target audience is. Do they want it for the common Joe or for the technical Joe. In either case, they fail horribly. Structure is poor and inconsistent, vocabulary improperly used, charts and graphs often times could be simpler, and so forth. If you haven't written or document many process or procedures do kid yourself into thinking you can just pick it up and start writing. Look at the new Ars Technia, poor articles being thrown left and right simply because they want the quantity out rather than quality articles. And if you still you can write better than those that are in the field, do yourself a favor and judge yourself by taking a class or attending seminars. I guarantee that most will come back thinking otherwise.
You can create visio workflows, and then publish it as an html file, with links to a wiki, where people can update and edit the details of each step. I did this as a proof of concept, but it never got traction.
I'll set up an example if people are interested enough.
http://brettevanson.com/contact
If you are looking for something with a simple flowchart interface like Visio but with a lot more power and ease of use, take a look at http://www.procelerate.com./ The product is called Vdot and it sounds like it can easily do what you want. // full disclosure, I work for ESI Group which recently acquired Procelerate.
I have to agree w/ the people who recommend you hire a technical writer. Find one with knowledge of structured writing systems using XML or DITA. DITA is an XML variant specifically designed for technical writing. it allows you to tag your content for various levels of competence, for example. Let's say you write for advanced, intermediate, and newbie skill levels. Tag the content as such in a single source file and rely on your transforms to provide the user w/ the level of content that he needs. Transforms can deliver your single source content file in whatever format you need, from printed docs to wikis. there are many more benefits to structured writing mechanisms which you can look up on your own.
Visio sucks. Use Smartdraw. There's lots of computer-related clip art so creating visuals is easy. The images also export into MS Office with no difficulties.
Past that, I'd use Wiki as a presentation server.
I was thinking about this a few weeks ago, and realised that what I really wanted was a kind of interactive checklist system.
Imagine a wiki based checklist that supported expandable trees of information. Advanced users can simply tick top level items as completed, and if you need more help you can expand levels of the tree as needed, providing more detailed steps, or more information about the process.
Ideally you would have something that can save completed checklists, but just having the lists available to work from would be a great help.
Of course, with a small IT department, it really wasn't worth fleshing the idea out further, or developing it. For our needs I've found that a wiki works great (mindtouch deki actually - bloody superb product). Checklists are easily tagged, and written with bulleted or numbered lists, and further information is easily added and cross-referenced.
Took two days to copy/paste over 400 pages of documentation into it, and it's the best decision we've made in years.
A picture is worth a thousand words... literally. Using screen shots helps a ton when creating documentation, just a tip.
a) mediawiki - there's simply no reason to bother with anything else.
b) Continuous Process Improvement - have the folks documenting what they do be responsible for improving and measuring those improvements.
c) OpenOffice - has an import/export that handles common mediawiki formating. It is really simple for those who can't learn the basics of *, #, = and == tags.
Whenever the process changes, those changes are documented in the wiki. If anyone wonders how they should perform a specific task - "it's in the wiki" is a standard answer. If they complain that it isn't correct, then they need to fix it.
I worked very briefly at Dell, doing corporate tech support (hardware), and well not to brag but I was still #1 in the stats ranking a month after I quit until my averages rolled off... anyway I spent much of my off-call time trying to figure out a way to condense my smarts and experience into easy-to-follow instructions for my neighbours, who were often struggling with what I considered very basic problems.
To put things into perspective, my average call time was 5 minutes. That includes the occasional hour-long clusterfuck, which means the great majority of my calls were under 5 minutes. The top 10 techs had averages in the 15-20 minute range, and most everyone else was 45 minutes and up. Well now what was I doing differently, besides being the guy with the most hands-on PC experience ? I was being lazy, that's what! And I was committed to sharing my lazy ways with the rest of the crew.
During the exercise. I learned a few things:
1. It is damned hard to put into words things that are trivial (to you)
2. Logic, much like common sense, is a rarity these days
3. Most people fail to factor in the true cost of support time
So for #1, I had a non-guru friend take instruction, helping me dumb things down and bridge the gaps until we both agreed he had mastered the situation. He would express his frustration at my poor instructions, and ask a zillion questions until I had a grasp of my own internal thought process, of things that I did automagically.
For #2, I ran through a large number of scenarios and wrote down my own inner thoughts at each decision point. At the end, I trimmed these down to a rather large, multiple-entry flowchart. The neat thing is it covered both specific problems like "my hard drive is dead" and fuzzy symptoms like "my screen is blank". You would start at the edge, identifying the main symptoms and then you followed the paths until they crossed. At the very middle was the final solution "Replace entire system", the catch-all in case no other endpoint was satisfactory.
For #3, I dug up details on the approximate cost of support time. This included salary, utilities, and amortized equipment cost. Then I made a list of common support resolutions and their total cost (parts, labour, shipping). This allowed me to show how a long call can actually be more costly than replacing the computer in its entirety, especially if the extensive troubleshooting still leads to component replacement.
So in the end, we had verbose instructions, a troubleshooting cheat-sheet, and a cost guide. It may have enabled incompetent techs to perform tolerably, but more importantly it gave everyone the tools to learn very quickly. After a week or two with these troubleshooting aids, many people had the common issues memorized and had developed strategies of their own.
That's what I consider a successful transfer of knowledge. Knowledge is much more than just static information, it's also the process to create more information.
-Billco, Fnarg.com
1. Your company is less likely to send managerial positions over seas. 2. At age 40, you should have aquired experience that makes your time more valuable than gold. 3. If you're in a managerial position, being fully trained on new technology is not necessary. You only need to know enough to properly manage your associates. 4. New college graduates do not have the experience needed to effectively and efficiently manage. 5. Ok, so you can't do too much about absurd deadline demands. This is not unique to IT by any means. But with higher levels of experience comes more bargaining power.
Nope.
Either you have had some great experiences or I have had some really shitty ones; either or, I completely disagree with you.
Write scripts for machines to follow, not people. If they are semi-intelligent, the people can figure it out from the script. If not, they need a new career anyway.
I used to be in the troubleshoot everything camp, now I am firmly in the copy the user's crap and re-image camp.
I also found this PC boot failure flowchart to be of immense help.
http://www.fonerbooks.com/poster.pdf
Beyond that my procedures stuff is pretty high level, stating what is required and letting the operations folks implement it how they like.
The nitty gritty stuff I have had to write has been pretty specific i.e. DISA compliant CentOS box running Snort, and that's because the DISA and NSA docs for Linux aren't current to RHEL 5.2 and the guy who's Snort install doc we were using died.
http://www.internetsecurityguru.com/
However I am thinking a Wiki would be sufficient for most folks needs, I like Mediawiki, it was one of three packages that came with my webhost, and it has been easy to use.
I work on the teach a man to fish theory most of the time, and ask my analysts and other coworkers to come to me after Google not before. But as a rule of Thumb if you had to find the answer to a non trivial problem through Google it might be a good idea to copy and paste it into the internal wiki rather than rely on you remembering your search terms, you being at work, and your internet connection being up the next time it breaks.
I deal with this on a daily basis. From a complete documentation point of view, the real need is to document overall goals, processes that work to achieve those goals, and procedures that support each of your processes.
The difficulty is, even in a reasonably small organization, this fans out to an enormous number of documents. The idea of Folding + Wiki is interesting, but of real value would be a system that allows you to declare a procedure (a step-by-step description of a function) that maps to a corresponding process (more general or conceptual description of the hows or whys), which in turn easily maps to the overall goal.
Example:
I can set a Goal that is a 99.99% SLA for applications I have to support. The goal document would describe the SLA and possible exceptions, who requires it, etc.
I can set up Process that state that each system in each of the applications will be monitored every 5 minutes, and notification of problems will be communicated to OPS staff immediately. The Process would describe any tools used to do this.
Then, I would have a series of Procedures describing what to do in case of a problem with any individual hardware or software component within any of the applications. These would be step-by-step, and would not necessarily require the user to have any special knowledge.
Problem is - I have yet to find a system that allows me to put these together and easily link them, allowing a user to understand what to do, and why it's being done, all by looking through the Goal-Process-Procedure linkage. If they can understand what, how, and why, they can better deal with problems that arise that we haven't accounted for, and assist in making procedures for those as they arise.
Guess I need to start writing one...
Eagles may soar, but weasles don't get sucked into jet engines - Unknown
I was going to say MediaWiki is the bomb, but nobody says that anymore...
Our company set up MediaWiki. If you link FCKEditor to it, you can enable your entire organization to do things otherwise impossible without rich media. If you want to get really good with it, link an Adobe Flash Media server with it, and embed videos as well as diagrams using Visio.
We've gone the whole nine yards and set up LDAP authentication with it, so some pages can be restricted. Some pages generate dynamic output with Perl scripts.
Then, you can get really creative and have command output actually framed around instructions.
I was tasked with this same issue in a huge corporation where I can't control the hiring of only useful people, nor could I spend the $$ to educate those who needed it. I used a Sharepoint site that had full DR and tracking for changes, tasked people to create a simple document for tasks they commonly did, then I just created a Master Document that contained sections with links to the documents that others had created or the ones that I created. The master document is currently about 90 pages of links to documents. Updates to any document are approved before posting to the site. There is a document template for any new processes that are created and they are tagged with review dates to ensure they are kept up to date.
The secontions in the master include "Basic Tasks", "Problem Determination" or "Standards"
Seems to work for me and the 200 other people that use it. It is available to 1000 people but only a fraction use it. Can't fix that with any documentation or application.
I like starting out with an overview like you do, but I made my living for a couple of years writing technical documentation for lawyers. They didn't want to understand anything. They just wanted simple, idiot-proof instructions:
. . .
Start out with a simple statement of the objective: Follow this procedure to find out where the network problem is. Indent for sub-steps, and use small text boxes to define things like "valid traffic". Use a consistent style; for example, we always used bold face for anything the user would see on the screen.
If the people using your documentation want to understand stuff, they will ask you to give a seminar, or they will even RTFM as you did.
"Who controls the past controls the future. Who controls the present controls the past." -- George Orwell
The most effective I have seen is people trained to use Information Mapping methodoloies. Seriously, if you have project budget, don't invent the wheel, get the people with the right skills. Wiki entry at http://en.wikipedia.org/wiki/Information_mapping
Pick me, I'm clean
pic+text documentation of procedures is good.
But people are often better at copying or mimicking than understanding static documentation and then reproducing the original actions or steps.
So often adding good videos can help explain things better.
For example, if you are documenting how to make a cheesecake. Just having the recipe in text and pics doesn't tell you everything.
You can state how fast the mixer should spin in rpms at different stages of the recipe, but there are so many details, that if you write down every detail in text, people either can't understand the whole thing, or will give up reading it.
Once they watch the video, they have an idea of how "fast" it should look, how the mixer would sound, how the mix should look at each stage.
Then:
1) It's easier to do the "hands on" training.
2) At least some might notice when the mix doesn't look or flow "right", and go get help to fix it.
To get people to understand and do things properly you might need stuff like:
Text+pic docs
Flowcharts
Checklists
Videos
Hands on training
Apprenticeship
MediaWiki is ok. Moin does a better job with attachments. Stay away from egroupware.
We use Camstudio (newer versions of VLC can do this too) to record videos of us doing common tasks, and publish to a server. This makes it a breeze to document a lot of simple stuff like "how to open a PuTTY session" that would otherwise be really time-consuming to write and insert and annotate screenshots. This leaves more time to document things that really need documenting, and immediately quashes all those complaints about instructions being hard to follow from people who can't find an icon or menu entry or whatever.
The other thing we do is create shortcut scripts and macros using AutoHotKey or xbindkeys that simplify otherwise complex tasks. This reduces a lot of small repetitive tasks into "run this script", which both simplifies the task itself in addition to making the documentation much shorter and less error-prone.
Of course, while I'm doing this I find it hard to keep myself from chanting the mantra: "go away or I will replace you with a very small shell script" to myself...
... is knowledge crystallized. The more of that you have, the less you have to put into procedural documentation, and the less you depend on the lower skill sets reading it correctly.
now we need to go OSS in diesel cars
Very well said.
I went to great pains to try to explain this to and convince a prior coworker, who had unfortunately injected this bad assumption into my boss. Eventually I couldn't deal with the endless hours of documentation, documentation approvals, documentation change mangagement, ad nauseum, which overran my job and took more time than doing real actual work (which was what my position entailed). So I quit and moved to a much better climate.
THE MAGIC WORDS ARE SQUEAMISH OSSIFRAGE
my favorites in this realm is pro-engineer by PTC for your actual blueprints
and mathcad by PTC for calculating your design... It is the best in my opinion for
handling units and including OLE objects of all your other design inspirations.
the issue we have at my workplace is ancient network documentation and too many changes. We create network overview docs when we first get a new customer and update them from there. Problem is we have a clunky .doc based system inside a svn like document manager. End result: no one bothers to udate them. We recently moved the user tauthentication lists to a secured intranet DB that is easier to update. Procedures are harder as we have helpdesk grunts and sysadmins that occasionally have to do each other's job and the knowledge gap is huge. Throw non-windows anything in the mix and it gets worse. We're currently evalating TikiWiki as a solution.
Documenting technical procedures is bad for job security.
Just so you know, I always advise the suits to fire anyone who they suspect of following this philosophy.
Better to get the hurt over with as soon as possible, the longer such a person works for you the more hurt they save up... nobody lives forever.
I know a guy who became a VP (at what is now a fairly big company, few hundred employees) for doing this while I got a lower bonus because I documented and was replaceable (I left two weeks after that review). If you work for a crappy company obfuscation (or just rewriting critical code in a language your co-workers have not used) may help your career.
You got me into this! You were the ideologue! I'm only a poor assassin! - Twenty evocations, Bruce Sterling
Lots of them.
OP, you could try to re-invent the world. Or you could hire a professional whose job it is to do exactly what you're looking for. They're called Technical Authors or Technical Writers.
As far as a flowchart etc., what you want is dependent on your needs of course. The simplest answer is probably a help document. Look into Robohelp.
Better yet, hire a Tech Writer.
Have a top level of "put stuff into box" - "magic process box" - "output from box" and then drill down repeatedly from there. Otherwise write a standard operating procedure that everyone follows. You have to make certain assumptions as to the readers knowledge, if they aren't sufficiently trained to know those assumptions they shouldn't be doing the task.
I think they manufacture and sell US Automobiles...
//Nothing to see here, please move along.
Not the way you're thinking. Where I work we use a wiki (mediawiki) and it works as well as any system I've seen, probably better than most. Now for the "can't be done" part:
Tasks like building a server, installing some software, connecting cables, etc., can and should be documented. Troubleshooting however cannot. Troubleshooting takes profound understanding of all the parts surrounding an issue and how they inter-operate; the ability to think long, hard and meaningfully; the ability to devise experiments, execute them, collect and analyze data and arrive at meaningful conclusions based on all that -- the scientific method, in other words. This is the kind of job that humans do better than machines and it is proverbially difficult to even understand, let alone document -- witness the "expert systems" of 20 years ago.
The big problem is that all non-technically-inclined people, including most people in management positions, think what we do is something mechanical akin to what plumbers do -- no offense to plumbers, who do things I can't do. From a user's point of view, "I can't print my e-mail message" is not much different from "I can't wash my dishes". Locating a clogged pipe and clearing it does require some technical skills and can certainly be documented. The e-mail printing problem however is several orders of magnitude more complex than that and, although it's probably possible to write a flowchart to document any possible thing that could be wrong in this scenario, it would be ludicrously huge, silly really. And that's talking only about day-to-day. If I'm really good at what I do I will design and implement systems so that errors of that sort are minimized. In other words, we're being asked to do the job of civil or hydraulic engineers on a plumber's salary.
There, of course, is the crux of the matter. Microsoft in particular, but the whole industry actually, are guilty of selling to managers the idea that this job can be done by drones, at all levels. Management is happy because drones don't cost much. Then, of course, drones are all they can get for what they offer.
What you want is knowledge, knowledge that can be provided by some, but by no means all, not even most, of the people who work for you. And you're tired of seeing those few good ones go away, leaving mostly drones behind. The only advice I can give you is: do document what can be documented. Make it a priority and make everybody responsible and accountable for documentation. But do acknowledge the really knowledgeable people in your team, treat them and pay them just as you would any other kind of expert. I know you're probably not in a position of paying your tech guru at orthodontist levels, but try to treat her at least as well as you do accountants.
You saved me some typing!
The older they were, the better they were built.
This is because of the building code.
Today, builders build to code, and the code specifies bare minimum safe method. As new techniques are developed to cut costs, the code is modified to allow cheaper, less redundant methods.
Before the code, builders built in competition with each other. They tried to build better houses, so they would have better reputation, so they could charge more.
But now, they just build to code. Full stop.
There's a place near me in PA that has no building code. All the buildings there are fundamentally stronger and better, no lie.
I try to apply this to programming. If a programmer doesn't write code good enough to stand without external documentation, I find another programmer.
Of all the things you mentioned, the wiki would likely work best. MediaWiki is pretty easy to setup on a LAMP stack and has the benefit of being identical to Wikipedia as far as editing goes. At my last job (tech support call-center), we eventually implemented a wiki. It started out as an awesome repository of knowledge, protocols, and even some email reply scripts. However, it quickly devolved into only 3 people really making edits (Me and 2 other guys had edits in the thousands, #4 top editor had a couple hundred). Instead of the wiki becoming the #1 spot to look up an issue, instead most of the techs would send one of the top editors a jabber. To which we would usually respond with a link to the wiki page with all of the info. It seems that the people who use it most are those that put effort into making it. Perhaps a push to have all of your users make contributions would alleviate this problem. Just my 2 cents.
Said, "It's just like dice but it's got more sides And it tells me who lives and who dies"
You could have high level articles with your procedures and within those links to item definitions which are in their own articles.
Just like when reading about WWII on wiki, you can click on Eastern Front which would lead you to another article and within that one you could click on Battle of Stalingrad, and so on and so forth.
I believe the concept would apply quite well to your predicament. Maintenance should be rather straighforward as well.
~Syberz
http://bitnami.org/stack/dokuwiki
This is an installer stack that will get it working on a windows box no muss, no fuss. It uses files in directories rather than a database so backups are a snap. You can include screenshots, there's an integrated search engine, all the features you could ask for.
I highly recommend it.
Kwisatz Haderach
Sell the spice to CHOAM
This Mahdi took Shaddam's Throne
I just posted a blog rant about some of the responses I just read @ http://blog.kevinbehr.com/ Over the last 10 years Gene Kim and I ( @RealGeneKim on twitter) have done countless hours of research in to high performing IT shops and what it takes to turn around those that aren't performing well. I can tell you that much of the high performers success hinges on the detailed specification of work and all of it's implicit assumptions.
Having been a technical writer in the computer industry for over twenty years, I can tell you from experience that the best approach is to (1) set up a wiki for technical folks to contribute content and simultaneously (2) use a professional technical writer to build and maintain a knowledgebase drawn from that wiki content and code comments, plus their own interviews, research, diagramming, and writing.
Do not try to solve this problem using traditional desktop publishing tools, except as a short-term stop-gap measure. Find a technical writer who understands both relational database and XML technology, and put them to work using their preferred toolset.
Some knowledgebase toolset notes follow.
Adobe RoboHelp Server 8 can be the delivery mechanism for an enterprise-wide knowledgebase and RoboHelp 8 can be the authoring environment --
http://www.adobe.com/products/robohelp/
http://www.adobe.com/products/robohelpserver/
with various additional authoring and diagramming tools serving as content creation editors, especially to cope with producing documents needed urgently, albeit in desktop publishing mode.
While RoboHelp got its start as a Windows online help editor, it has, like the gawky teenager next door, grown into an impressive adult over the past few years.
A competing product you (and your technical writer) should also look at is Macap Flare, which was developed by a group of software developers who spun off from RoboHelp a while back.
(RoboHelp had been successively owned by Blue Sky, eHelp, Macromedia, and now Adobe, with the all the personal stress such corporate buy-outs, and the resulting rebranding code-churn, can induce.)
Madcap Flare is also part of a knowledgebase-creation toolset that will soon have its own content management server as a delivery and workflow mechanism --
http://www.madcapsoftware.com/products/flare/
http://www.madcapsoftware.com/products/teamserver/
The Altova XMLSpy toolset is also worth evaluating --
http://www.altova.com/solutions_center.html
Don't expect your techies to spend their time in Altova, Flare, RoboHelp (or whatever), since their time is much better spent writing code and comments and any descriptions they can generate, in tools they already know and love, such as wikis and their favorite IDEs.
But do expect your technical writer to follow along and clean things up in a high-end knowledgebase toolset, and, eventually, to set up a workflow process for copyediting and approving new and updated material, but in as unobtrusive a manner as possible.
Also be aware that your knowledgebase will likely need to be translated into multiple languages, with the advice and assistance of localization specialists.
It sounds like your technical writer will be doing catch-up -- it has typically taken me about 18 months to get things under control and flowing smoothly in any company that neglected to hire a technical writer from the beginning, all the while jamming out whatever documents were needed for product delivery using standard desktop publishing tools.
This is not a life to envy, or for the faint of heart, but it can be an adventure for the truly dedicated. Bringing order out of chaos with your keyboard can be a rush.
It's not really something that can be distilled into documentation.
If your IT department is half up to snuff it'll have asset and change management databases, a knowledge base and a library of technical documentation. This should be sufficient, provided you have the people to pull it all together.
So go to your management and say you can document everything except the fine art of troubleshooting, it's not possible to. That said, a good search able knowledge base goes a long way (Wiki's often have inadequate search). You'll find your more astute techs using google heavily, and using google to search something like Microsoft knowledge base, or other wikis, forums and KBs, because the built-in search is usually rubbish.
Documenting technical procedures is bad for job security.
The unfortunate and somewhat inconvenient truth is that there will always be a protectionist culture in IT. Too gooder documentation will mean management will ask serious questions about why they need expensive staff with qualifications when they see how simple some things really are - that someone who has natural smarts and the Knack, can do the same job just as well as long as you can let them get at the information they need.
Not that this doesn't happen, that some outfits have the inspired idea they can employ an army of monkeys, give them some instructions and watch revenue roll in. Only to find that it doesn't work.
Seriously, in our industry we make money out of things that are broken, always need improvement and have planned obsolescence. It's a fine balance, and perfectionists from other areas may not like the way we do things and ask for things that are somewhat impossible and likely detrimental so tread carefully. Very carefully.
After logging in slashdot still does not take you back to the page you were on. It's been that way for 20 years.
1. Your company is less likely to send managerial positions over seas.
Hah! Who are you going to manage if your entire department is sent out of the country? You can't just send work to China or India and expect the workers to manage themselves. You WILL need someone on site or disaster is all but assured. Yes there is some need for some local folks but someone is going to be shown the door. I've got a lot of experience in global sourcing and anyone who thinks management won't need to go overseas along with the workforce are deluding themselves.
2. At age 40, you should have aquired experience that makes your time more valuable than gold.
Easy to say but not really possible for everyone in the real world. The world needs specialists and if your specialty changes underneath you you're probably going to struggle. Even if you plan for various contingencies, sometimes life just isn't so cooperative with even the best laid plans. Changing careers at age 40+ can be incredibly challenging, especially if you have family depending on you.
3. If you're in a managerial position, being fully trained on new technology is not necessary. You only need to know enough to properly manage your associates.
And if you are management with no technology expertise you are that much easier to replace. There's no free lunch here. Management is a skill just like engineering and managers can be replaced too.
4. New college graduates do not have the experience needed to effectively and efficiently manage.
This is generally but not universally true. I graduated much older than many of my classmates because I worked through college. I certainly had the experience to manage small teams and in fact did.
5. Ok, so you can't do too much about absurd deadline demands. This is not unique to IT by any means. But with higher levels of experience comes more bargaining power.
Sometimes the Faustian bargain you make to get more experience or higher in management is to submit to more absurd deadlines. Customers are often the ones setting the deadlines and they are notoriously unforgiving if you can't meet their expectations - realistic or otherwise.
What I really want is an open system, preferably openoffice based, that also combines the benefits of wiki-like multi user editing and version tracking. We're stuck using Word because it's so much faster and easier for our documenters to use. Basic things like being able to copy and paste a picture into a document and then draw text and arrows on it is something that a wiki just can't do. I've even looked at wikis that have wysiwyg editors and they're still too time consuming and difficult to use. I've considered Sharepoint but cost is an issue and I'm very gun shy about complicated Microsoft solutions. Is there a Sharepoint-like open source system out there?
Sounds like an xml schema waiting to be developed to me.
Pug
An Invisible Entity of Vast Power whose existence must be taken on faith alone: Liberal Media
you could outsource everything, then you KNOW there is no competency
dont make the perfect youtube video, just make the damn thing fast but accurate - speak it out - there's no time to type and review.
Better in native language.
A very densely linked hypertext seems like the solution for what you describe. While you could possibly do that using a wiki or html authoring system, its much easier to develop something like this on a hypertext authoring system such as StorySpace from Eastgate Software, and then export the results to a static HTML environment, if that's what you want, or keep it in Storyspace to take advantage of its linking that goes beyond what HTML supports.
Here's a thumbnail sketch on one approach. I've used this, to develop SCM processes, procedures, roles, and responsibilities for a 600 person development organization. About 1/3 of that organization consisted of contractors.
It took us a little under one year to go from 0 to revision 1 of the system (including vendor selection, piloting, etc.).
The challenges are really the following:
Once these issues are established, then it's just write, test, revise, test, revise, test, and publish.
I'll give you some scenarios, but the actual implementation is specific to the organization.
1. Deciding who the audience is
This decision will frame how the document is written, what level of detail the document contains, and the general structure of the document.
From your description, it sounds like you have a lot of contractors who will be unfamiliar with your processes and procedures. In that case, you'll probably need some environment documentation and some process documentation in addition to procedural documentation.
Deciding what the purpose of the documentation is
This decision will drive the detailed structure and the language of the documentation.
For example, if the documentation is primarily for education, then keeping the information at a structural level with a few well-chosen examples works well. If the documentation is operational in scope, then a use case type of structure can work well. Finally, if the document is focused on teaching, then an underlying example, lots of repetition, in-line exercises, and documented sequential steps seem to work well.
From your brief description, it sounds there are two purposes. You need to educate incoming contractors concerning your environment and processes. You also need operational documentation.
3. Deciding what are documentable processes / procedures
"Everything" is not the answer to this step. Everything that is not industry-standard might be an answer to this step. A more reasonable answer might be whatever impacts performance metrics.
The level of impact can be assessed, and target topics can be put into MoSCoW (must have, should have, could have, want to have) order. This will make the documentation task more manageable.
4. Deciding how the documentation gets used
I see a lot answers jumping to this area. Flowcharts, wikis, web pages, SharePoint, etc. are all technical solutions to this issue.
However, the question has not really been asked. What is the normal work pattern of those people who MUST use the documentation?
If they're seated at a computer with either multiple screens or multiple windows, then online, hyperlinked documentation may be a good fit. The delivery mechanism (actual technology) is up to you.
If people leave their desks a lot to accomplish tasks, then a different format will be needed, as well as a different document structure.
The goal in answering this issue is to make sure the documentation gets used. For that to happen, the documentation has to be a natural extension to their current work habits.
Hammering out the Issues
For the truly ad hoc organization (CMM 1), an assessment followed by a series of JAD sessions works well. This may seem like a waste of time (let's get writing already), but it helps to identify the best use of effort, and it gets everyone on board with the process.
Many people view documentation as constraints, so getting everyone on board via a CMM assessment and JAD sessions is important.
Creating the documentation
Once these issues are hammered out, then the documentation can be created. Writing documentation, especially detailed operational documentation, is tough. One way to ease the pain is by adapting
That, sir, is a damn smart way to tackle the challenge. As a self-styled Geek Ambassador to the non-geeky world outside of my IT office, I tip my hat to you, and will adopt your way of thinking.
Document it as if the reader is a total moron.
That means that in any group following the instructions, you have a better than evens chance of one of them being able to understand them and not need to phone support (i.e., you).
Yes, that means screenshots if applicable of every stage, with clear instructions. You're the sheepdog, they're the sheep. Don't use fancy language, and de-techify the text as well.
Quick question: what about those of use who are developers who get virtually no time to document our work, even though we'd (myself) would love to.
I totally disagree with everything here.
never ever document stuff, especially trade secrets.
Ive seen people laidoff just as they've documented systems or completed a project.
happens every time.
then too I saw guys recently laid-off, only guys in their group with a clue, the company canned them because they thought they could do "without" and that the morons were smarter than the people who really knew what they were doing?
result: in most cases the companies went out of business. in other cases the projects were canned and the groups disolved.
no one had a freaking clue what they were doing. I ain't never gonna give them any info that could help them. not a chance.
BTW my favorite was the guy who left "deadman" switches in all the systems he admin'd in case they decided to get stupid. yep, they did, oh the full ensues when the deadman systems engage. whoo
Back to the future :
http://en.wikipedia.org/wiki/Scientific_management
1) Everyone is different
- What works for you won't work for other !
2) Your interest is not the same than those of your workers
You should look into professional documentation writing companies that are specialized in applying authoring structures to your information. Usually what happens is a text writer will sit with you to create the structure and then fill it in with your input. You would be surprised at how effective this is, for you and the user. They help you select the correct medium that best for the user. Also, remember, you're not documenting this for yourself, but for the person who will be following the instructions. Job security is moot in this situation - they hire you for your effectiveness at implementing the solutions. I used to work with a Netherlands based company that did this www.landl.com Its not cheap, but it gives excellent results.
Read what I mean, not what I wrote.
In other words, when you say "we have to document every procedure and process, no matter how mundane or 'common sense' it may seem," you've already lost. You don't need meticulously documented procedures, you need to take those "varying degrees of technical competency" and educate them to a higher level of competency.
If you are a 24x7 shop, the on-duty people need the home and cell phone numbers of the people that know how to fix each possible thing that can go wrong. And you need a wiki that they consult first for standard procedures. Then it is up to the technical people to decide whether they want to keep getting calls in the middle of the night or type up some step by step instructions.
As you document, you should be automating. Then you can have a help desk tech even run your "fix user rights to porn websites.sh" script, if you will.
At my work we use a wiki (running Confluence).
We write both technical and process documentation and put it in the wiki.
Repeatable tasks are documented. If someone does something that's not already documented then the expectation is that they document it.
The other thing is that when new staff members join or if there are staff members who aren't as knowledgeable we give them small, less critical tasks and sometimes buddy them up with people who know the ropes until they're capable.
We also have a section for vendor manuals.
Wiki; whatever simple wiki runs on the server infrastructure you have in-house. I use wiki for just this purpose because:
- it's easy to take overview ideas and push them down into their own detail pages as it becomes apparent that that's needed (for example, your 'valid traffic' definition);
- actually, it's easy in general to keep modifying and tweaking. This kind of knowledge is, by definition, not fixed.
- it's easy for users to update, not just you. So when someone else has a good idea about how something should work, they can push it into the documentation directly. If someone finds something that's not quite right, they can correct it.
- it's searchable.
- at every point in time, the wiki represents the accumulated knowledge of the organization.
medicine-like
or even a doctor-like
already enough to be a major in the university itself
so all guys are professor......
and ur boss wants u to write "the whole thing" for those elementary students......hahaha
You can use plain text or formatted HTML to create pages (attachments are easy to add) and it's easy to organize pages into an outline or (surprise!) a course format. Moodle also lets you set up forums, wiki's and so on.
Wiki's are good, but it takes some work to organize the pages. I like to create an "index page" for ease of navigation. You can do this with wiki trails in PmWiki http://www.pmwiki.org/wiki/PmWiki/WikiTrails
In MoinMoin http://moinmo.in/ you can use Categories to group pages.
With Moodle and wiki's, authorized users can edit the pages, including data in tables. which can be handy.
For personal notes,you might try:Tuxcards http://www.tuxcards.de/, KeepNote http://rasm.ods.org/keepnote/(it easily handles screenshots or other images),Jreepad http://jreepad.sourceforge.net/ a plain-text-only outliner, or BasketNotePads http://basket.kde.org/. Like Tuxcards, Basket can export its contents to an HTML tree, which can be posted for others.
If you are adventurous, use a mindmap, such as FreeMind http://freemind.sourceforge.net/.
There is no replacement for a good admin....PERIOD!!!!
Rpath have a wiki VMWare appliance, that was also available as a bootable image. (http://www.rpath.org/rbuilder/project/vehera-base/ ) Built and customised a wiki while waiting in a departure lounge. About an hour.
(Getting the vsftpd running took a little longer)
As I tracked every config change, moving from VMWare to a stand-alone box was completely painless, including moving all the images and data.
As a bonus you get a full LAMP stack - adding Mantis to the mix was seamless.
Ignore claims that is is now deprecated by a new (but unfinised) project.
-- Butlerian Jihad NOW!
That way, no one on your UNIX systems will be able to read it.
But don't stop there!
Email the document to all of your users. Then, when they do something wrong, you can ask in a condescending tone, "Didn't you get the procedures document I sent?"
But don't stop there!
Use the latest version of Word - you know, the beta version, which means the format will be unreadable to everyone in the office except you. When you present to senior management, bring your laptop to show off how easy it is to follow this simple document. When things start to go awry, blame your subordinates and suggest that perhaps some of the work should be outsourced.
But don't stop there!
When you've finally outsourced the entire department, pull the same trick on the company with which you've contracted. When they can't meet deadlines/SLA, (because, of course, no one can read your stupid Word doc...) - blame them for breach of contract. Publicly berate them in front of your superiors for their ineptitude.
But don't stop there!
When senior management finally figures out that you're the problem, suggest that perhaps they should bring the work back in house. Save your word document as HTML and post it to the company's intranet site. When things start going smoothly once again, take all of the credit for "turning a troubled company around". Make sure you get your bonus.
The society for a thought-free internet welcomes you.
We use PmWiki for all of our system documentation. It allows for the ease of use and wide accessibility of web based documentation, but it is also dirt simple to install and run (no database to worry about) so that it can be put on a thumb drive or dumped to a PDF for portability. It also has a simple, solid mark-up language that lends itself to importing plain text notes.
It sucks to have your documentation "go down" when you need it. That could happen with a more complex wiki, but would be highly unlikely with PmWiki.
"Anyone that thinks Documentation might lead to their dismissal because "We don't need him anymore" is dead wrong. If you write documentation, you'll be the most loved person in all of IT in your company."
True enough. My job is putting together training documents. Well, part of my job anyway. I get emails every day saying 'What would we do without you?' for just sending out an email with a couple of screen caps and a couple lines about how to perform a task. If it doesn't have to be fancy record the procedure on your cell or camera and give them a video to reference.
1. Get an idea of what co-workers are doing.
2. Get enough shallow information to draw conclusions about what tasks are the biggest wastes of their time.
3. Create a procedure or document an established procedure that will cut their time on those tasks.
Time is all about respect. If I waste your time I don't respect you and if you waste my time you don't value me. Save someone 10 minutes a day and you just saved them an hour for the week. That's an hour of their life they just got back which is worth at least $6 in the US. If you saved an hour of work a week for 30 employees you just saved your boss over ten grand for the year. I made a few changes to a procedure and documented it today. It took me 5 minutes and saved 29 employees 5 minutes each day.
Getting the procedures out of peoples heads is a huge money saver for the business down the track. Check out www.businessfitness.net. While we mainly deal with accounting firms out software can be used for any business and has a number of features to help facilitate better procedures. We provide basic templates for procedures, checklists, letters etc and this system has been specifically built for Document and Record Management. Hope this helps. Either way when writing procedures ensure that someone else reads them that does the same function or even better get someone to follow your procedure while you do the function and if you miss a step they can pull you up and get it added to the procedure.
DocBook or DITA are two XML vocabularies designed to write technical documentation and procedures. Coupled with a CMS like Calenco (shameless plug), you can write procedures independently, and then gather them inside whole documents, in a modular and versatile way. Additionally, you can in the same procedure, tag chunks of information as being, for example, basic or expert information. Depending on your audience, you can then output documents in various formats (PDF, html, etc.) with the information directly relevant for your target.
ChadDa3mon, the approach that you suggest is good. Start with an overview, and progressively give more detail. For information about the process of documentation, see 'How to write user documentation' on http://www.techscribe.co.uk/ta/how-to-write-user-documentation.htm.
It does matter what you use to document and how you store the documentation. If no one can find the correct doc when needed, or if they don't know a doc with the necessary info exists, you've wasted your time.
The Eclipse Process Framework is designed explicitly to design and document processes. It ties together disciplines, processes, roles, domains, work products, guidance, and tools. It's extensible. It comes with OpenUP, a lean open-source process library based on RUP. You can start with OpenUP and modify it to meet your needs, or you can write your own from scratch.
It can run error checks to make sure that you have tied up all your loose ends, so that you don't end up with a process that produces some piece of work but nobody was assigned to create it.
You can publish it as a static web site, or as a web app (wrapped in a WAR file.)
Just download it. It's free, Open Source, and based on Eclipse, of course. Go through a tutorial and you'll go "wow - this is exactly what I asked Slashdot for."
John
I would recommend you check out Lombardi Blueprint http://www.lombardisoftware.com/bpm-blueprint-product.php (disclosure I work for Lombardi). Its designed to be easy to use by all, is browser based and collaborative. It has a high-level view like you're talking about ("Discovery Map") Which then generates a flow diagram at the touch of a button. It also generates documentation. The Map, Flow and Documentation are all linked so if you make a change to one it will change the other two. We even have a 30 day free trial offer :-)
Good luck!
A manager who does not know why you should be documenting also does not know why you should be kept on the payroll.
I deal with our DAM system (for librarians and end users) and our b2b website (worldwide, but mostly U.S.). Users vary from "where did it download on my computer?"-level to more advanced.
Though I often want some fancy wiki or specialty software, I've found that the fastest/easiest/least breakable solution is to just create a point by point instruction manual for the majority of the processes that have to be done. Each one starts as the same Word template, and follows the completely basic "hand holding" steps the user takes along the way, with screen shots of how it should be looking at that point. I save each as a pdf so I can send them and keep them locked.
Nontechnical users have a piece of paper they can set next to them, and use step by step, and more advanced users can skim and get to the points they need.
Easier than dealing with the added level of problems that "How do you use this wiki?" and such would create among the less techie users!
It was a small company and I know everyone involved. The "correlation != causation" is great for statistics, it does not help for small sample sizes where things are known.
There were other factors, but bad documentation really helped his career, while good documentation hindered mine. I've worked for saner companies since, and it's not the boom any more.
You got me into this! You were the ideologue! I'm only a poor assassin! - Twenty evocations, Bruce Sterling
I really like the two facing page user manual technique. Each pair of pages is a specific 7-9 step tasks and the TOC lists all of the tasks. You will want to include pictures with each specific step (instead of referencing figures on different pages). Create links between tasks instead of repeating everything.
You can combine this with a fast-track approach, where you make two columns on each page, the left column has more detailed steps and the right column is more generic and can even be just screen shots, so someone that has done it before or is familiar with the interface can just skim down the pictures to do it quicker.
This technique (there are books on it, sorry can't find my copy right now to give you an ISBN) allows users at any level of knowledge to get into the process at anypoint that they need help. They just look up the task in the TOC and they should never have to turn the page during the steps. Since the whole TOC is task oriented, there isn't really any issue with how long the document gets either.
Although this works really good with printed documentation, not sure how well it translates to the web (or pdf for that matter).
Try FreeMind. http://freemind.sourceforge.net/wiki/index.php/Main_Page
Mind map providing very similar to what you described. You can show general outline at a high level and drill down to the details below it. FreeMind can be "published" in a number of formats. Easiest is to a web page using its Flash plugin - no exporting or converting required. Can also be exported to click-able map / text if your descriptions are longer than comfortable in the map.
Yea, it matters eventually, but it doesn't matter WHAT you use usually. I think the Wiki idea is a good one, but my point was that the most important part of a documentation library is the documentation itself. Don't let the fact that you have no great place to put documentation get in the way of generating it.
Most methods of storing documents also has the ability to text search so even if you begin with a dumping ground of random documents on a file server you should still be able to locate what you need until such time as you decide on a document management system.
- It's not the Macs I hate. It's Digg users. -
If it doesn't flow linearly from start to finish it's useless for 99% of users. Jumping off points? They either won't bother, or if they do (most likely by accident) they'll just become even more confused.
The other 1% could probably work it out for themselves anyway.
Confucius say, "Find worm in apple - bad. Find half a worm - worse."
Indeed, the amount of detail put into the steps depends entirely on the intended audience.
Building up documented resources/knowledge based articles and maybe even product doc with accurate good content (since always good to also be mindful of the customer's perspective that product doc provides) in a WIKI is the only way to work efficiently and reduce confusion within a company - and yourself. Keeps it public, keeps lots of eyes on it to fix or improve it, keeps people working consistently, actually helps motivate and encourage additional innovation through online collaboration... etc. To suggest that doc is a waste of time is a complete joke. You might not like doing it - but that's another issue. It is needed - people in corps should not work in a silo. The world is more robust than a single shallow viewpoint of the person that feels doc is useless. Working efficiently means sharing your desktop, and also being able to take advantage of someone else's shared desktop. WIKIs provide this, though also keeping WIKI content organized is also important - nothing more irritating (and time-wasting) than a nasty nest of outdated content where nothing is reliable. If outdated, move it aside or out of the way. Keep a clean hierarchy of info, and keep your life sane. And in the end, get more done - everyone. I'm biased to Atlassian Confluence WIKI, alot because of its integration with developer tools, and being the most feature-ful of the WIKIs out there - but really these goals can be accomplished by lesser featured WIKIs as well.
Excellent.