Survey: What makes for high-quality documentation?

  • 2
  • Article
  • Updated 9 months ago
A technical writer in the industry reached out to me to see if the TechSmith customer community could help with a research project he's conducting. If you can take a few minutes to respond to his anonymous survey about how readers define documentation quality, please do:

https://www.surveymonkey.com/r/JSK9ZL9


The survey asks you to rate the importance of 15 documentation quality dimensions, as well as consider how their presence/absence in technical documentation makes you feel. The survey is not about any particular company's documentation, but rather about technical documentation quality in general.

Thanks!
Photo of Daniel Foster

Daniel Foster, Snagit strategy lead

  • 861 Posts
  • 192 Reply Likes

Posted 9 months ago

  • 2
Photo of Rick Grunwald

Rick Grunwald

  • 1249 Posts
  • 856 Reply Likes
That is not a well written survey. I gave up about half way through
Photo of Joe Morgan

Joe Morgan

  • 5650 Posts
  • 2929 Reply Likes
I didn't take the survey but I looked it over and the criteria. The verbiage used in the questions was confusing.
 
SO how would you rate the survey? Is it safe to say that you......I Dislike It: Extreme dislike; can't accept it; major issue.   
Photo of Joe Stoddard

Joe Stoddard

  • 16 Posts
  • 17 Reply Likes
That survey is ridiculous, beyond poorly written. I also gave up It's not going to generate any usable/actionable data for you IMO. That said let me say that I would EXPECT all 15 of your adjectives about documentation to be present and true, and if I encountered documentation at a client that did not - it would be replaced. Period. There is priority however. Accuracy is CRITICAL and would take priority over minor formatting issues or writing style.
Photo of Rick Grunwald

Rick Grunwald

  • 1249 Posts
  • 856 Reply Likes
It is amazing that they stay silent on the destruction of Snagit, chronic bugs but ask the people who are doing a lot of support to do this. FOr a client. A client that does not understand technical writing by the looks of it
Yet they are the new fair haired children  ...  I have to ask though. IF this is the new "Technical writing client" that  with whom they are so  enamoured to the point of destroying the program. And said client does not understand technical writing to the point of creating a coherent questionnaire ...
... are we seeing nothing more than some good old boy cronyism hijacking a once great program for their personal agenda? I hope SENIOR management takes notice of of what just happened here and reads between the lines and stop pretending that a very small contingent is making a mess out of their company
I saw this at IBM although they have the inertia  to keep going Montgomery Wards died at the hands of a "really smart guy" (details if you want them) a poor Woolworth had a small contingent of old men who wouldn't listen and set up the new Woolco stores they way they saw fit.
Sadly, Techsmith seems headed that way and there is no will in management to take ahold of the disaster and turn it around. Thier 3 million users that are touted when they want to remind us that we are not worth crap ARE crap. That is nothing when compared to the inertia of the giants I mentioned

If this sounds bitter, it is not. I have just seen it all before and am astonished that ... here we go again/   
Photo of Joe Morgan

Joe Morgan

  • 5650 Posts
  • 2929 Reply Likes
I have to admit, this so called survey?

Is what I call the perfect example of Zero Vetting by anyone. Or it was vetted and TechSmith was so hot to trot to kiss this customers ring, nothing else mattered.

Here, take this embarrassingly poorly thrown together survey. It's for a client we want to "Land or Keep" forever.

What did you say? You want an audio level meter for Camtasia?  Dashed outline shapes for SnagIt for Windows? Maybe next year, there wern't enough votes to support that at this time.  
Photo of Rick Grunwald

Rick Grunwald

  • 1249 Posts
  • 856 Reply Likes
I have seen a couple of instances where there were a lot of vote before the one who can do no wrong decided that there were NOT enough votes.
Photo of Joe Stoddard

Joe Stoddard

  • 16 Posts
  • 17 Reply Likes
If someone wanted to evaluate  something along the lines of   "Documentation: Which of These Criteria are Most Important to YOU" --   (15 is  arguably too many) .   All you need is  the  Criteria,   and a simple 1-10 scale for each one  with "One (1) being completely UNimportant  and  ten (10) being "Mission Critical - the documentation cannot exist without ) 

A. Accuracy:  The information is factually accurate     1........5.......10  
B. Clarity :  The information presented  is easily understood     1........5 .....10
C.  Multi-Lingual:   The information if presented in English and Spanish or  (other)   1......5......10  
         OTHER:  List other language(s) you believe are necessary  [text box]

Etc.  
Note however that  the original list of "critieria" is highly ambiguous..  "Concise" and "The Appropriate Amount" are essentially the same thing.   Ditto  "Valuable"/ Reputable/Relevant  ...  .  
Any survey that depends on the reader's interpretation of the criteria is  immediately flawed...  "what is "valuable", exactly?   Is it lIterally "what the market is willing to PAY FOR" - or something else?    S

Something "Accessible" to me  (I have broadband) might be completely INaccessible to you (you live off-grid) .   Well-written surveys leave nothing open to interpretation.  Even if  the aim is totally subjective  (What do you FEEL...xyz... (in other words... your OPINION)  the criteria still has to be universally understood  or the total of those opinions mean nothing . 
Example:  the question  "Should Guns be Made Safer? "   What kind of guns?    How "safe" are they now,  and what, exactly constitutes "safety" when applied to firearms?   

Finally - in any "graded response"  the responses have be mutually exclusive  *degrees of the same thing*.   "I expect it"  and "I like it"  and "I can live with it"  are THREE completely unrelated responses which are not mutually exclusive. 

Example  Question:  WHAT ABOUT  PAYING FEDERAL INCOME TAX? :   I  definitely "Expect" to have to pay my taxes.....  but  at the same time  I don't like it... and at the same time "I can live with it"  .  Those responses are NOT degrees of the same thing and they are not mutually exclusive .  Unless you're allowing "check all that apply"  having responses that are unrelated won't yield useful data.  

You could  poll to determine "degrees of expectation"  among a population (Employees,  Students,,, whomever)   
"To What Degree do you expect documentation to be accurate ? 
1 (no expectation of accuracy ).......5.......10 (totally expect to be accurate) 

"To what degree can you  tolerate inaccuracy in documentation
  " 1 (INtolerable) ..... 5 .............10 ( totally tolerable) 
And so forth.    
Photo of Bernice Stockstill

Bernice Stockstill

  • 3 Posts
  • 0 Reply Likes
So what do you need? tech writer or what? 
Photo of Daniel Foster

Daniel Foster, Snagit strategy lead

  • 861 Posts
  • 192 Reply Likes
Nope, any user of technical documentation.