Discovery: There is no "Getting Started"

But there is no help.  Or not much.  So all us discovery types are doomed to be diamonds in the rough, really Jody?  No, I'm saying we're treating discovery a little like Kenny's lesson.   Some of you have been thrust into the position of "Discovery Person", with something like that to go on.  "Ok, repeat after me.  This is a CI."  You, dutifully:  "This is a CI."  Lesson:  "Great, now let's sing along:  the input trigger's node's attribute's value's parameters' limits are dependent on the use cases' consumers' data's decisions' value in order for the adapter's jython's Main's parameters' values to be interpreted correctly."  You fall over unconscious, only to awake to realize it's not just a nightmare.  It's nightmareware.

 

Yes, LOL indeed.  But it happens.  Technically correct but newbily useless content, wearing a suit.  Buh lah.

 

And then all the in-between questions are annoying to both parties.  What's that again?  What did it do?  What's this connected with?  Yes, I understand.

 

A good Getting Started Guide is hard to come by.  You have to put yourself in the right place.  You have to assume the dankest conditions, 2am, presentation at 8am, nobody to call or talk to, and you haven't taken any lessons.  Like a budget-imiting-decision-for-you if you fail kind of obligation to get it working..   

 

Remember a while back I blogged about Wild Angry Bees and why your ITSM Vendor needs them?  It was an allegorical and somewhat smarmy look at how Vendor - Customer disconnect causes software disonance; how customers and vendors confuse each other, and a milquetoasty attempt to bridge that disconnect.  Anyway, I blog again here to raise the same analogy with documentation. 

 

Sometimes one imagines the Developer not caring about creating effective documentation.  But they do care, it's just really difficult to create perfect documentation.  And yes nobody's documentation is perfect.  My point is that documentation is only perfected through diligent attention to customer experience, through documentation of what happens in all the labs of our world, and how to apply new knowledge to solve business problems.  We need to shorten learning curves, improve understanding, simplify big ideas.  How to be that overworked technician learning on the fly at 2am.  How to not assume anything.  How to provide stepping stones from one step to another without losing your balance.  It's easy if you know how.  Our developers know how to do this exquisitely.  Does your vendors'?

 

So my Survey Question for You the reader today is, what is your documentation pet peeve?  What doesn't the doc you're forced to deal with do?  How do you change things?   How does one "get started" best in your opinion?

 

What Would Kenny Do?

 

What Would You Do?

 

Get Started.  Talk to us.     Doc pet peeves, let's hear 'em.  Thanks! JR

Comments
JasonRoiz1 | ‎09-15-2011 03:14 PM

Someone is finally asking me about my document pet peeves :) Here they are:

 

1) One should speak english as a first and native language in order to write good documentation! I get a headache reading documentation from non-native english speaking countries, no matter how well they have learned english.

 

2) Document everything!

 

3) Protectionism - If a tech puts everything he knows on paper, their has to be a feeling that he/she is now more replacable than before. CIO's openly proclaim how they're trying to get rid of american employee's and offshore. I wrote documentation so Shell could offshore it's storage systems to Malaysia at 1/3 the salary. I interviewed (extracting info) the high-paid american storage expert and then handed over an operations manual to the malysians so they could run it from there. They were whittling away at his job one item at a time.

 

It is hard to write good documentation and it takes time, which employers may get impatient with. Documenting isn't easily seen as "getting things done" unless your a consulting company. It's very hard to maintain and keep them "evergreen" unless there is a systematic way of doing it.

Jody Roberts | ‎10-06-2011 11:17 AM

Jason, thank you for your insights.  On your #1 point, I agree with expansion:  Most of the business world does speak English.  As a vendor though, we have to publish multi-language documentation.    Every version should be checked by a native speaker of that language, who ALSO knows something of the subject matter.  I've found it difficult to see good documentation without both of those things in place.

 

#2 of course.  But in the face of #3 i understand some of the misplaced purpose of documenting everything, if one feels one's job is being taken away once everything is sufficiently documented.   If I were that person, and I wanted to keep my job, I might not be so sure.  Or, I would just do #2 for more, different subject matter.  

 

I have found that documenting the things I work with to give me more job security, rather than less.  People like what I write, so they want me to write more.  Specialization is a dicey business.  Generalize and become a general.  Specialize and be treated like an insect.   But don't sacrifice depth.  Be shallow and you'll evaporate.

 

Finally, if employers don't see documentation as "as necessary" as the "real" work, I would look for another employer.  The more complex the machine, the better the doc you need to operate it.  Operating by tribal knowledge is a slow-cooker recipe for disaster.  Don't.  Skimp.  On.  The.  Documentation.  Period.

 

And I agree most of all with your last sentence.  Yes yes yes.  Everybody.  What Jason said.  Documentation is a process, not a project.

 

Thanks again, very good comments.

JR

Leave a Comment

We encourage you to share your comments on this post. Comments are moderated and will be reviewed
and posted as promptly as possible during regular business hours

To ensure your comment is published, be sure to follow the Community Guidelines.

Be sure to enter a unique name. You can't reuse a name that's already in use.
Be sure to enter a unique email address. You can't reuse an email address that's already in use.
Type the characters you see in the picture above.Type the words you hear.
Search
About the Author
Jody Roberts is a researcher, author, and customer advocate in the Product Foundation Services (PFS) group in HP Software. Jody has worked ...


Follow Us
The opinions expressed above are the personal opinions of the authors, not of HP. By using this site, you accept the Terms of Use and Rules of Participation