Documentation- The Never Ending Game
-
You could spend your whole life documenting every little thing. Here are a few questions I ask myself before creating a document. Can this be easily memorized? Will I forgot this completely before I have to do it again? Can I share this with others to do the work for me? Would this be something I'd likely be doing again? and the best one "Is it worth my time to create this document". Many variables answer the last question.
-
And I never document common knowledge. It is a big temptation to document how to do everyday tasks that should be part of the job description rather than something unique to the organization.
-
@scottalanmiller I believe that depends on the area of work you do. L1 helpdesk? Document everything in my opinion. Honestly I got hired with more ambition than applicable experience, so it was mostly trial by fire for me.
-
@FiyaFly said:
@scottalanmiller I believe that depends on the area of work you do. L1 helpdesk? Document everything in my opinion. Honestly I got hired with more ambition than applicable experience, so it was mostly trial by fire for me.
Even so. You can't document the job itself. Once you are repeating industry documentation you are playing a game of doing a lot of work and providing nearly zero value - possibly negative value.
-
Part of what you have to consider is that documentation has a cost. Making documentation that has no value still has a cost to maintain. Documentation gets old, especially if you are documenting industry practices. For example, if you document how to do a normal task in Windows today, and you hardly ever look at that documentation because you can just Google it or people just know it, then that procedure changes because of a new release or change of tool or whatever, now you have documentation that was previously valueless but today is a risk. All that effort to create, store and search knowledge that is wrong. That's not good.
-
The big problem with not documenting what YOU think should be common knowledge may not be so common. So over documentation is better than not enough
-
@Minion-Queen said:
The big problem with not documenting what YOU think should be common knowledge may not be so common. So over documentation is better than not enough
Not common knowledge, but industry knowledge. If you are duplicating Technet or the Red Hat Admin manual, for example, you are just making lower quality copies of existing knowledge. Anything that is standard and universal shouldn't be documented internally. It carries a lot of risk. Decent chance that it is just wrong, high chance that it will never be used because why would someone look internally first, almost certain chance that it will become dated and nearly certain that the cost to maintain will make it always negative.
-
One of the biggest problems with documenting industry knowledge is that it will never end. There is so much to potentially document. You will eventually document more than can be maintained. And the internal documentation has no chance of being the "master", it will always be second class to public documentation (like Technet.) It will never become the reference standard. You will always be challenged by a combination of people not bothering to look at internal docs because external ones are higher quality, finding internal documents is harder than finding the originals (via Google), the cost of using special internal docs is higher than standard ones (that people use at home, at other jobs, etc.) and just not realizing when they can or cannot use them.
-
Also, never document something someone has already documented. IE Google first
-
@Aaron-Studer said:
Also, never document something someone has already documented. IE Google first
Yeah, that's kind of what I was saying. If someone else is already maintaining that documentation for you, don't do it again. At best, link to the public site or make a cached copy if you need to.
-
@fiyafly It is a business maturity component. Documentation fits into several larger pieces such as DR (disaster recovery) and BCP (business continuity planning). Another way to view it is not having documentation is a risk. Senior business management needs to accommodate the risk level accordingly (i.e., BCP which trickle down).
Having things streamlined helps reduce duplication of effort. Duplication can be by multiple people, or the documentation existing in multiple systems (e.g., printed docs and the change control system). Time is always a notable constraint
Reasonable ways to assess documentation satisfaction level is:
- during a periodic review (annual is preferred);
- when a new employee comes on board;
- when an experienced employee separates; and,
- when bad things happen.
Triple constraint concept and good-fast-cheap apply to the quality and effort applied to documentation—
-
I like to use Evernote for quick note taking on my mobile while away from my desk.
-
Evernote is pretty slick. I just use Onenote for that though.
-
No one else here mentioned this, but I document everything for myself.
I document projects, daily tasks, common fix-its, and etc for myself. It does a few things for you. It shows you are a team player, it shows your value, it shows other potential employers your value, and you can CYA if anything ever goes wrong.
-
@IRJ said:
No one else here mentioned this, but I document everything for myself.
I document projects, daily tasks, common fix-its, and etc for myself. It does a few things for you. It shows you are a team player, it shows your value, it shows other potential employers your value, and you can CYA if anything ever goes wrong.
Also shows that you have a lot of spare time
