In the message dated: Mon, 01 Mar 2010 19:56:28 EST, The pithy ruminations from [email protected] on <[lopsa-discuss] How to improve documentation habits> were:
=> So, I suspect like at least a few of you, I suck at documenting what => I've done. Unless I make a conscious effort to do it as I go along, => it often doesn't get, as the next fire takes priority. Absolutely. => => One thing we've implemented recently at work is a documentation queue in => our ticketing system. The idea being that if someone is looking for => information and can't find it on our internal documentation site, they => can drop in a ticket and the person responsible for that => system/service/whatever should get the appropriate docs written. This => (maybe) solves the problem of forgotten/overlooked documentation. Sounds good. => => But what about keeping up with documentation as tasks are accomplished, => new systems are stood up, etc? What tips do folks have for getting => better at documenting in their daily tasks? I include documentation in the "budget"...whether I'm doing an estimate in my head or presenting a more formal project plan, there's always a documentation component. This way it's clear that documentation is an integral part, not an afterthought for which it's difficult to justify the time required. => => There are definitely procedural things we could do to improve this, and => we should probably be doing those, e.g., no system goes into production => without full and proper documentation. But we're not there yet, and => sometimes the nature of $WORK necessitates deploying things before we're => fully ready. That's a political issue, and has to be overcome in other => ways. => => So I guess what maybe I'm looking for is tips to help me improve outside => of the procedural/operational framework. Things like "spend the first => 15 minutes of every day documenting what you did the previous day" or Not a bad idea...though I'd shift it to "spend the last 15 minutes documenting what you did that day". Even when I'm not in a job position where progress reports or time tracking is required, I find is a helpful reminder of where my time was spent to jot notes on the day's tasks. This isn't formal documentation, but can serve as notes to be fleshed out later. For me, this method works well with the "documentation on Fridays" kind of practice. What does Tom have to say (see Time Management for Sysadmins or The Art & Practice...)? => "make the n00b on the team do all the documentation." I like that as a training tool and a way to expose whether existing documentation is sufficient, in the absence of senior team members....but it's no substitute for on-going internal docs written by the people working on each project. => => OK, so maybe that 2nd one is just wishful thinking :) => => -josh Great topic! Thanks for bringing this up. Mark ----- Mark Bergman Biker, Rock Climber, Unix mechanic, IATSE #1 Stagehand http://wwwkeys.pgp.net:11371/pks/lookup?op=get&search=bergman%40merctech.com I want a newsgroup with a infinite S/N ratio! Now taking CFV on: rec.motorcycles.stagehands.pet-bird-owners.pinballers.unix-supporters 15+ So Far--Want to join? Check out: http://www.panix.com/~bergman _______________________________________________ Discuss mailing list [email protected] http://lopsa.org/cgi-bin/mailman/listinfo/discuss This list provided by the League of Professional System Administrators http://lopsa.org/
