One question i have - sorry for the top post - how much of these documentation problems are because people think they have to write incredibly comprehensive, really good documentation? Someone saying they aren't a good enough writer to do SA documentation makes me think they are aiming too high.
One thing I've talked to my team about is that *some* documentation is better than *no* documentation. Write *something* down, and then start evolving it. I heard way too much of people saying things like "I need to take a day off by myself to write the documentation". Since the "day off by myself" never happened, we never got documentation. Start by writing a basic checklist, and have people fill it in with more detail as they work through the processes. When I was a more hands-on guy i was fairly successful with writing some low quality but accurate documentation as I went - as I would be working on a project, I would document the new procedures and processes as i went, and try to use the documented procedures as i worked through things. When i was disciplined about doing this, we ended up with some useful documentation - really more of the checklist type of thing Tom was talking about earlier, but it was pretty helpful to the rest of the team. The thing we *didn't* get with this style of doing things was documentation of *how* things worked... just more about how to manipulate the infrastructure. Dana On Tue, Aug 10, 2010 at 11:16 PM, Luke S Crawford <[email protected]> wrote: > Jefferson Cowart <[email protected]> writes: > >> On that note, any suggestions on how to get people to write [good] >> documentation? Others in our teams seem to be very resistant to writing >> even basic documentation. (There are a couple services we provide that I >> don't have documentation on what system hosts the database.) I'd guess >> I've written 90%+ of the documentation on our wiki. While everyone >> agrees it's a good idea, no one makes the time to write it. > > If you figure it out, let me know. > > I know what motivates /me/ to write documentation is allowing that > documentation to be seen by the public. But yeah, it's /really hard/ > to get people to document things. > > I've tried saying "Dox or it didn't happen" but that doesn't seem > to work, either. I'm considering some kind of documentation > bonus, but I'd need to come up with a documentation metric. > > I think my root problem is that I have a SysAdmin who isn't very > good at writing. He doesn't enjoy it because he's not very good at it. > "Oh, a script would be better than documentation" he says. > Now, I'm not going to fire the guy; there's no way I could get a SysAdmin > who was as good of a SysAdmin as he is /and/ a reasonably good writer > for what I'm paying him. > > To be fair, when I was his age, I wasn't very good at writing, either. > but I think that's the root cause. I wonder if some kind of writing > workshop could be the solution? I think my writing is passable, > and I learned mostly through writing, and then getting made fun of > by the Internet. > _______________________________________________ > 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/ > -- Dana Quinn [email protected] _______________________________________________ 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/
