June 15, 2017 at 6:43 am
GilaMonster - Wednesday, June 14, 2017 2:11 PMjasona.work - Wednesday, June 14, 2017 9:32 AMWhile I know there are mistakes in my documentation that I don't know about, I've always felt the best way to write documentation is to presume that your Mom / Grandma / 5yr old niece or nephew is going to be the one having to follow those directions. Presume they'll need everything spelled out and anything that can cause a problem needs to be bold, italics, and a 24pt font with multiple warnings.
And even then they'll manage to break it.I generally write that kind of thing as if the first person to use the documentation will be the junior DBA who's on call on Christmas afternoon, and if he can't figure it out he's going to phone me
That's one of the things easier said than done, even though obviously it's a great goal. The time taken to write the document and keep it up with every change will generally fall on the most expert in the organization (you don't really want the docs written by an intern) and few places have that kind of resource continually free.
...
-- FORTRAN manual for Xerox Computers --
June 15, 2017 at 7:24 am
GilaMonster - Wednesday, June 14, 2017 2:11 PMjasona.work - Wednesday, June 14, 2017 9:32 AMWhile I know there are mistakes in my documentation that I don't know about, I've always felt the best way to write documentation is to presume that your Mom / Grandma / 5yr old niece or nephew is going to be the one having to follow those directions. Presume they'll need everything spelled out and anything that can cause a problem needs to be bold, italics, and a 24pt font with multiple warnings.
And even then they'll manage to break it.I generally write that kind of thing as if the first person to use the documentation will be the junior DBA who's on call on Christmas afternoon, and if he can't figure it out he's going to phone me
So, step 1 in your documentation then is "If you're not sure if you should call the senior DBA about the problem, call the senior DBA immediately."
June 15, 2017 at 7:29 am
jay-h - Thursday, June 15, 2017 6:43 AMGilaMonster - Wednesday, June 14, 2017 2:11 PMjasona.work - Wednesday, June 14, 2017 9:32 AMWhile I know there are mistakes in my documentation that I don't know about, I've always felt the best way to write documentation is to presume that your Mom / Grandma / 5yr old niece or nephew is going to be the one having to follow those directions. Presume they'll need everything spelled out and anything that can cause a problem needs to be bold, italics, and a 24pt font with multiple warnings.
And even then they'll manage to break it.I generally write that kind of thing as if the first person to use the documentation will be the junior DBA who's on call on Christmas afternoon, and if he can't figure it out he's going to phone me
That's one of the things easier said than done, even though obviously it's a great goal. The time taken to write the document and keep it up with every change will generally fall on the most expert in the organization (you don't really want the docs written by an intern) and few places have that kind of resource continually free.
Ideally this process in question (provisioning a local development environment) should have been a PowerShell script with input prompts and warning dialogs, rather than a Word document that reads like instructions for assembling an IKEA bunk bed. Better yet, DevOps could have provisioned the dev environment in advance before the author's first day started.
http://www.ikea.com/ms/en_US/customer_service/assembly/T/T60078604.pdf
"Do not seek to follow in the footsteps of the wise. Instead, seek what they sought." - Matsuo Basho
Viewing 3 posts - 16 through 17 (of 17 total)
You must be logged in to reply to this topic. Login to reply