Getting Info from a SME

I hadn't been out to the Techwr-L site in months so I was pleasantly surprised to see this article: How To Interview a SME

Related to the TWer Job I Posted About Earlier Today

The source for the Technical Writer position description within Uh, No!! was not properly cited. It came from the Techwr-L list. There has been an interesting thread about the position description, including whether it was biased.

At 10:04 AM today, a link was posted to a gender decoder. I never knew such a thing existed! This is the link that was posted to Techwr-L: http://gender-decoder.katmatfield.com/results/aeeb0213-89a1-4ee9-83ce-ee7da512afb2

Uh, NO!!

Facility with technology

• You’re curious, not afraid to be hands-on with the products, and you can empathize with the challenges our customers face.
• Expert level understanding routing, switching, and fabric technologies for Data Center networking
• Hands-on experience configuring routers, switches and firewalls
• Experience in virtualization platforms (e.g. OpenStack) or container environments (e.g. Kubernetes) is highly desirable
• Know the craft—You like writing more than you like doing anything else and you have an innate ability to think like and write for administrators. You see every feature and task as part of a broad scenario, and interested in not only how something works, but also when and why to use a particular configuration/setting.
• Innovation—You are creative, and love to experiment with new ways to present information in a way that enables a positive user experience with our products.
• Organization—You can take large amounts of technical details and organize them into topics that users can easily find and use to solve their network problems.
• Initiative—You’re not afraid to propose changes to improve process and quality to enable a better customer experience and you are relentless in hunting down the information you need.
• Interpersonal skills—You are able to work with developers, QA, PMs, customers, SEs, and support to successfully gather information required to understand the problems our users are facing and the ways our products help to solve them.
• Problem solving skills—You have strong critical-thinking skills and use them to ensure that you are providing just the information our users need to complete the task at hand.
• Adaptable—You can handle a rapid release model and adjust easily to new or changing circumstances.

Qualifications

• Must have expert level knowledge of networking, network protocols, and APIs. Having a CCNA/JNCIA certification is desirable.
• Ability to see the big picture and proven track record of writing from scratch.
• Writers/Engineers with proven experience of documenting Solution documentation, App Notes, Whitepapers, Configuration documents and API docs .
• Proficiency with FrameMaker, Adobe Acrobat Pro, Help N Doc, and image editing tools is desirable.
• HTML experience is desirable.
• Familiarity with Bugzilla (bugs) and Confluence (collaboration) is preferred.
• Ability to work independently or with minimal supervision. Experience working in a startup environment is a strong plus.

Finding Relations

I am in a good mood today and I'm making you, the reader of this post, a promise. Here it is. I will answer this prompt prior to the end of this post:

So who [of the Big Bang Theory characters] do you relate to the most? 

To answer that prompt, here's another question for you. Where were you yesterday and 24 years ago?

I was at 200 5th Avenue in downtown Cedar Rapids, Iowa, for a job interview at Network Data Processing (NDP). A friend of ours had gotten drunk at our New Year's Eve party on 12/31/1994 and told me all about how great NDP was, which is where he worked. Long story short, my interview was at 8 AM and before noon, I had accepted a job offer from John Millard - I was hired for my first technical writing position on the same day as my interview. These are the companies I have worked at as a technical writer:
NDP
Jordan Systems
Quintrex
the Unnamed Hellhole in southern Iowa
Pearson
University of Iowa, which is where I work now. I spend my workday adding my experience and expertise to two major projects: Disaster Recovery documentation and Knowledge Management.

When I have worked as a technical writer for 24 years, 1 day. My personal plan is to work another 17 years, 1 month, 2 weeks, 3 days (6255 days) here in this department. If I do that, I will reach 20 years of service at the University of Iowa. I will be 66 years, 3 months, 3 weeks, 3 days as my 66th birthday will be 12/4/2035, but I would need another 3 months, 3 weeks, 3 days (115 days) to reach that 20 years of service milestone.

Over the course of the last 24 years, I have met and gotten to know many fellow technical writers through the Techwr-L list. Tony Chung is one such technical writer - this is his website that I've browsed in the past: https://tonychung.ca/. I know that over the years of my technical writing career, I've corresponded with Tony off-list. I don't know when we have or how often - it's just one of those things I know and you should accept my statements without question! 

It was on Friday, 2/8/2019, when Tony referenced The Big Bang Theory in one of his posts to Techwr-L. His comments about one of my favorite sitcoms prompted me to send Tony an off-list response. I included some links to Youtube.com videos during which Sheldon gives other characters instructions. That IS technical writing - my technical writing jobs have always been about software documentation, which involves a lot of writing instructions that instruct a user how to complete a task within software. While my current two projects are not directly tied to writing software documentation, there is a possibility that I may be able to do so . . . but it's too early to speculate on the likelihood of it happening - it COULD happen, it probably SHOULD happen, but I don't know for certain WHEN it will happen. Regardless, for the majority of the last 8767 days, I have earned a paycheck through working as a technical writer.

Which leads me back to Tony's email and my reply on Friday. I included 2 links (embedded for your convenience). First, there was Sheldon giving Raj instructions:

---

---

And then there was Sheldon giving Penny instructions:

---

---

I really chuckle when I watch that video because it includes this classic line from Penny.

All of that brings me to today. When I got to work today and checked my Techwr-L email account, I read Tony's reply. I immediately began to compose a response, but stopped myself, pasted the original draft of my reply into this blog post and started constructing what you have read to this point. To tie the conclusion of this post to the opening, it was Tony's prompt that caused me to spit these 774 words into this post. Here's my answer:

1. I am not exuding self-confidence (Leonard)
2. I hear a lot of fancy words that people might think I understand but I sometimes don’t but I’m hesitant to call attention to that (Penny)
3. I have a deep affection for comic books, super heroes, Star Wars, and other beloved franchises (Sheldon)
4. I was never a ladies man (Raj)
5. I had a somewhat overbearing mother, though not nearly as overbearing as Mrs. W, and I also married the most beautiful woman I’ve ever met (Howard)
6. I am not usually “thought of” when my friends are constructing plans (Stuart)
7. I am tall (Bert)

Ok. I give up :>(

Is it funny or sad that one of the most recent dialogues on the Techwr-L list ended in giving up. Today's discussion between Rick Quatro & Robert Lauriston was a back-and-forth of "point" followed by "counterpoint" until Rick gave up instead of arguing the likelihood of having trouble remembering that page 86 comes after page 85.

Editor's Note: This is the file Robert linked to when he wrote "Adobe doesn't do it any more either."
https://help.adobe.com/en_US/framemaker/2019/using/framemaker_help.pdf

Stucture in a Reference

-----Original Message-----
From: Me
Sent: Wednesday, August 15, 2018 8:12 AM
To: TECHWR-L
Subject: RE: Use of word "reference" when cross referencing

I prefer to specify why the user would want to go read something else prior to naming the other place so I use this structure: "For more information about the system layout, see Understand the System Layout."

---

-----Original Message-----
From: Lin Sims
Sent: Tuesday, August 14, 2018 4:34 PM
To: TECHWR-L
Subject: Use of word "reference" when cross referencing

I was taught to use "See section

for more information." when the information is in the same document, and to use "Refer to " when the information is external to the document.

Thoughts About Indexing

Updated with more thoughts about automating index creation.
-----Original Message-----
From: Mark Baker
Sent: Friday, July 27, 2018 8:49 AM
To: 'Jonathan Baker'; dick@rlhamilton.net
Cc: techwr-l@lists.techwr-l.com
Subject: RE: Looking for classes in indexing

Index automation can only take you so far. For the book I referred to earlier, we experimented with index automation. The book is about structured writing, so naturally we used structured writing techniques. This included the annotation of subjects mentioned in the text, and of the subjects covered in chapters and sections. This is essentially what an index does -- it points you to the places were different subjects are treated in a document. So it follows that we should be able to derive an index from these annotations.

This is already a much more controlled process than using software to scan an unstructured text for keywords, which is all that automated indexing software can do, short of an AI revolution that has not arrived yet. The subject annotations that we used noted the type of the subject and rectified the terminology (for example: {XML}(markup-language "Extensible Markup Language")). This gave us a significant degree of terminology control and allowed us to detect a lot of inconsistency in the book (as Richard mentioned earlier). It also allowed us to automatically create entries for the major types of subject matter discussed in the book:

markup languages
XML, 56, 68, 72
HTML, 345, 403
Markdown, 3, 76, 432

The result was a not bad index, but certainly not as good as Richard wanted. In particular, it did not let us do things like this:

constraints, 27, 228, 367–390
auditing, 431
cost of reuse, 153
data entry, 315
detecting duplication using, 414–415
extensibility and, 334
factoring out, 29, 42, 308
managing reuse, 134
media-domain, 29
personalization, 167
rhetorical, 246
semantic, 312–315
structural, 312–315
types of schema, 389
uniqueness, 174

These types of entries put terms in their narrative context. This requires a human reading of the surrounding text. It can't be done effectively from subject-domain semantic markup and it certainly can't be done reliably (yet) by indexing apps working on unstructured text.

Why is this important? Search engines have two big advantages over indexes (other than their enormous advantage in scope, which I mentioned earlier). First, indexes work on individual terms, while search engines can work with phrases and sentences. You can type an entire question into a search engine and it will use the whole sentence to discern what you are interested in. In other words, you can put your search terms in their narrative context up front by searching on the right phrase.

Second, they have a ranking algorithm that does a remarkably good job (most of the time) at selecting the most relevant entry and putting it at the top of the list. Indexes, by contrast, list pages in numerical order. If you want to get really fancy, you can bold page numbers for the main entries for a subject, but that is not in any way specific to the user's individual query. Search engines not only rank the subject matter statically, they rank it for the known interests of the individual user.

These entries that put terms into their narrative context help indexes partially make up for these deficiencies vis a vis search engines. They can only be created by hand, and Richard felt it was important to do this for the book, particularly in cases where a subject is mentioned many times. An undifferentiated list of 30 page references presents a rather daunting task to the reader. The context setting entries can help them narrow down what they are looking for.

We did not throw out the automated generation of the index altogether, however. Rather, we added markup that allowed us to supplement the generated entries with human created entries (100% of which were created by Richard, who is way better at this sort of thing than I am). As a result of this hybrid approach, we were able to reduce the indexing effort significantly, while still incorporating valuable index features than can only be created by hand.

I'm planning to blog about this and other aspects of the development process for the book sometime soonish.

Mark

> -----Original Message-----
> From: Jonathan Baker
> Sent: Friday, July 27, 2018 7:22 AM
> To: dick@rlhamilton.net
> Cc: techwr-l@lists.techwr-l.com
> Subject: Re: Looking for classes in indexing
>
> I’m not into religious wars, so I won’t go there. However, in following this
> conversation , it occurred to me that there may be some tools out there to
> automate the indexing process. I didn’t do a search, but did stumble upon a
> tool called TExtract (texyz.com). I haven’t used it, but may the next time I
> need to do an index.
>
> Also, one of the best books about indexing was written by Ruth Canedy
> Cross. Unfortunately, Indexing Books is out of print and only sometimes
> available on Amazon.
>
> Jon
>
> Sent from my iPad

---

Original Post below:
This is from a thread about indexing on the Techwr-L list which I am including here because I am weak at indexing and the links in Monique's email look like some sites I should investigate.

---

-----Original Message-----
From: techwr-l [Monique Semp]
Sent: Wednesday, July 25, 2018 2:20 PM
To: Lin Sims
Cc: TECHWR-L
Subject: Re: Looking for classes in indexing

Really old, but I have printout of an article from the October 2012 STC Intercom magazine that I found quite useful: The Top 10 Indexing Errors Made by Technical Writers, by Lorne Griffith. I imagine it wouldn't be too hard to find online. (And if it is, you can ping me and I'd be happy to scan it and send the PDF.)
And I second Lin's comments around the idea that digital search does not take the place of a good, human-produced index. For example, if the text says, "remove", but I search for "delete", I'll never find it. But in a manually-produced index, I'd expect to see an entry for "delete" that says, "see remove".
I was a member of ASI for many years even though, like Lin, the only things I indexed were tech docs that I wrote. But I thought of doing more (until I found how low the pay was for how much work it would take to write a really excellent, vs. mediocre, index), and I liked the erudite discussions among the REAL indexers.
It is unfortunate that ASI seems to require membership to take their courses. Maybe a personal note to them to ask for an exception might work? I did look at their webinars page, and those seem generally available to non-members, although the topics are mostly pretty narrowly focused to a given tool or a given indexing focus. See [1] https://www.asindexing.org/category/webinars.
The Portland chapter of ASI lists a bunch of non-ASI indexing courses: [2] http://pnwasi.org/wp/?page_id=141. Perhaps other chapters (don't recall where you are, so not sure if there's an active chapter near you) have similar lists of resources.
And here's a nice list of resources, including email discussion lists, but a lot of it is geared to people wanting to have their own indexing business. But of course, the email discussion lists would be useful for
all indexers. See [3]http://www.backwordsindexing.com/Novice/NoviceNotes.html.
And my last list on this listicles reply: [4]https://indexstudents.wordpress.com/education/ - lots of training and all sorts of resources.
(Yes, I like the subject of indexing!)

References

1. https://www.asindexing.org/category/webinars
2. http://pnwasi.org/wp/?page_id=141
3. http://www.backwordsindexing.com/Novice/NoviceNotes.html
4. https://indexstudents.wordpress.com/education

---

This post from Mark Baker was worth capturing as I like his writing style.

---

From: techwr-l [mbaker@analecta.com]
Sent: Wednesday, July 25, 2018 6:20 PM
To: techwr-l@lists.techwr-l.com
Subject: RE: Looking for classes in indexing

I'm old too, but let's face it, indexes are the paper substitute for a search engine. Anything an index can do, a decent search engine can do better (yes, including synonyms). More to the point, even the old are so habituated to search now that the only way they are going to stumble into your index is if it shows up in a search results.

Unless, of course, they actually are reading on paper, because then the index is the poor man's search engine, and in that case it better be good, because it has a lot to live up to.

And if there are those out there that still want to claim that indexes are better than search engines, here is the clincher: An index only works when you have a the right book in your hand. Which means you have to find the book before you can use the index. But a search engine searches everything. The reader does not have to locate the book first. Indeed, they probably never know which "book" their results came from. They live in a world of pages, not books, and they find pages using search. Every Page is Page One.

If I was looking for a course to take in this day an age, I would take SEO before I took indexing. Unless, of course, I was actually preparing a book for publication on paper. (Which, as it happens, I am: Structured Writing: Rhetoric and Process, real soon now from XML press. I think it has a pretty good index, most of which is Richard Hamilton's doing.)

---

Therefore, ... Walk

---

The above provided the means to reveal a truth about a situation in my career in 2010. One of the reasons I left that employer was due to my frustration with a Project Lead not keeping his word. Seeing Jack's statement, with the powerful second sentence Therefore, ... walk has just opened my eyes to what I was dealing with at the time.

Here's what happened.

I went to a meeting on a Monday to review a user interface. The user interface was to have all user actions on a right-click menu instead of a row of action buttons, as was common in most of the systems that company sold. I remember arguing the point that the user should not have to discover functionality with the Project Lead. The Project Lead countered with the fact that when you look at Windows Explorer, all the available user actions are not buttons. I conceded that but since there were a small number of user actions - let's say 5 - it made sense (to me) to have those buttons in a row on the screen. After much debate, the Project Lead agreed - buttons would be added to the screen.

The following week, I went to another meeting to review a user interface. The Project Lead was the same person, but he was not at the meeting because he was travelling. The screenshot in the specifications document we were reviewing showed a screen very similar to what had been discussed in the meeting the week before and, like the week before, there were no buttons across the bottom. Like the week before, I said, "Shouldn't we have buttons on the screen?" The person running the meeting replied, "No. The Project Lead said we were not going to have buttons on the screen." End of discussion.

From my perspective, we had taken a step backwards from what we had just agreed upon the week before. It'd be like if you negotiate with someone that they are going to accept Terms A, B, and C. The other person agrees to those terms. When you meet the next week to finalize the deal, the person says, "No, I don't accept Terms A, B, and C." It felt like the Project Lead was going back on his word. From a professional perspective, it felt like my opinion didn't matter if the Project Lead wanted to change his mind. From a personal perspective, I had always considered the Project Lead a decent fellow. I had never experienced him going back on his word to me, though I know in other matters in his life outside work, he had done so to others, such as his first wife, but this was really the first time I had been told one thing only to be told that that one thing was invalid the next week.

Looking back at that situation with the knowledge I've gained over the last 8ish years, I know what I would do or say differently to that Project Lead might not have changed his mind, but I would have made my case more strongly with evidence (screenshots of other systems) in an email. At the time, I let it become just another reason on a list of reasons to Therefore, ... walk.

Marketing Crap

Upon returning to work after a 10 day journey to New York City, I began the laborious task of weeding through my emails. This one made me chuckle:

---

---

To read the "marketing crap" for yourself and generate your own opinion, go here: https://clickhelp.co/clickhelp-technical-writing-blog/how-to-write-a-user-manual/

---

---

To read the referenced page, go here: https://clickhelp.co/software-documentation-tool/user-manual/context-help.html

A Reminder to Do Accurate Work

Yehoshua Paul, on Sunday, April 22, 2018 2:19 PM, sent the following inquiry to TECHWR-L with this subject What are the worst things that have happened due to content mistake?:

---

I will be delivering a short presentation on May 6 on some of the more costlier mistakes that have occurred because of a mistake in the technical content that was delivered.
The list I have compiled so far includes:

• A deadly helicopter crash
• Radioactive waste turned into bomb
• Mars Orbiter mishap
• Toyota recalls sports cars
• NYC Subway map typo

---

I thought it would be a great thing to remember as I am working on two projects that could have the same type of outcome:

• my disaster recovery documentation in RoboHelp
• Knowledge Management

1020 Hours a Week?!?

Sincerely, I hope they find a candidate for this opening that can convince the employer they will have 1020 hours per week to devote to completing an assignment. I'm no math major but 7 x 24 = 168 and 1020 hours divided by 24 hours in a day equals 42.5 days.

---

Again, to be clear, I am NOT looking to leave my current job. I came across this job because I received an email from "Kimble Group," plugged in my zip code, along with "technical writer" in the search criteria and this job was a "match" for me.

---

---

I also came across a part-time technical writer position that was posted 42 days ago! That's longer than Lent!

---

Again, to be clear, I am NOT looking to leave my current job. I came across this job because I received an email from "Kimble Group," plugged in my zip code, along with "technical writer" in the search criteria and this job was a "match" for me.

---

---

As Andrew Plato used to write "Back to work me!"

Putting Up Some Fences

From the Techwr-L list:

---

I almost can't believe I am writing this. We hired an internal candidate into a tech writer position. I am trying to mentor/train her. We'll be dealing with Word documents on Windows machines.

I want her to set up a folder structure to manage the files she'll be handling. I suggest Windows Explorer as the "right tool" for doing so.
Instead, she wants to keep everything on her desktop and use a software called "Fences" to manage everything.

I think this is a really bad idea. Am I wrong?

I try to be easygoing and offer "suggestions" rather than dictate things, but am losing patience.

---

Fences? What the heck is a software called "Fences"?!? Google, thank you for showing me this: Automatically organize your desktop shortcuts and icons with Fences®!. I downloaded & installed the 30 day trial. Because I was curious, I sought information about other similar products and, again, Google, thank you for showing me this: http://www.topbestalternatives.com/fences/. I'll fudge around with Fences before diving into the depths of alternatives.

I contributed to the thread with this post:
I get the points about being new, etc, but there's also the other side of the coin where 'existing people' (I didn't say 'old' on purpose <grin>) should also be open to a fresh perspective. It goes both ways.
For example, I worked at a hellhole for a short period of time with a senior department member who insisted on using InDesign with no application of styles - as in manually typing the TOC and the leader dots and the page numbers - for a 150ish page user guide. She would print the entire user guide and manually verify the heading in the body matched the TOC. If there was a discrepancy, she would make changes, reprint, and start over. She bragged about staying past midnight to get the user guide done because of that process. Being the problem-solver type I am, I showed her a small InDesign document with headings and a auto-generated TOC. How many hours could be spent on other tasks if the TOCs were auto-generated? I have no idea because she wasn't even open to a fresh perspective. I believe her exact phrase was styles were "too complicated" to implement. I still shake my head in disagreement. You can't convince me that in an InDesign file it is "too complicated" to apply Headings 1 -4 styles to text that is already manually formatted to look like a heading. I call that ignorance.
FWIW, I downloaded the 30 day trial of Fences and am giving it a test drive. So far, so good. Think of it as creating a folder on your desktop, putting files into that folder and being able to see the files in that folder without double-clicking. You can also make the folders roll up, which has already decluttered my Desktop. That's just my observation after a couple of hours of playing with it.

---

Sent off-list to Bob:
This is what one of my three monitors now looks like. The red boxes are fences that are set to roll up / be hidden until I mouse over them, the green box are icons I don’t have within a ‘fence’, and the purple boxes are fences I created where I am (currently) putting file types and folders.

---

---

The fences are just for ease of grouping things. When I view the Desktop in Windows Explorer, I don’t see any fences – all the files are within the “Desktop” folder:

---

---

Hey You! What's Your Number?

To me, it's funny how MS Word is so divisive on the Techwr-L list. When one person says "Word is fine for small documents," another chimes in with the comment that that person has "been using Word for long documents since the early nineties without problems. I'm talking 250, 500, 750 page projects, and larger." This is the thread I have been reading:
http://www.techwr-l.com/archives/1707/techwhirl-1707-00033.html#.WXsqoWfAvNI
Side note: The original thread does not display in the thread index, only a reply, as shown below:

Moving on to the actual point of this post, MS Word and numbering is something I have dealt with in the past. It was not long ago when I was fighting the linked MS Word documents in my RoboHelp project.
Here are some links about numbering:
https://answers.microsoft.com/en-us/msoffice/forum/msoffice_word-mso_other/problem-with-auto-numbered-headings/11675c6e-f1d9-4738-9bac-de54e38b6bc5
http://www.shaunakelly.com/word/numbering/numbering20072010.html
http://www.shaunakelly.com/word/numbering/numbering2003.html

Editor's Note: Unsure whether Shauna Kelly is given the gratitude elsewhere on this blog. She passed away in November 2011. Read more here.

Life at Another Employer was like THIS

At a previous employer (10/2010 - 4/2011), I was in the same type of position as Zev Levi, the originator of the thread below, except that I wasn't about working in a different country. In my situation, it was about:

• explaining to product managers and developers and a co-worker why their documentation ideas [were] troublesome 
• defending my 15 years, 8 months, 5 days of experience against terrible technical writing practices, chief among them being to manually type a table of contents for a ~150 page user guide, printing it, verifying the page number in the table of contents matches the actual page, fixing, reprinting, and repeating that process. 
• biting my tongue when, after showing my co-worker that an automatic table of contents could be generated from headings in the Adobe InDesign file (just like Microsoft Word), doing so was dismissed as "too complicated."

Thus, when Peter Neilson wrote "Attitude Adjustment being inappropriate, the solution devolves to doing an end run, never showing the final version to the SME until it is too late for enemy action. If the SME outranks you substantially, be ready to take a job elsewhere, preferably in an entirely different profession", I smiled and replaced the word "profession" with "industry" as that's exactly what I ended up doing.

In fact, 5 years, 10 months ago today, I left the medical devices industry. An incredibly long 1 month, 2 weeks, 4 days later, I began working in the education industry. I worked in that industry for 4 years, 7 months, 3 weeks, 5 days, which is when I had to begin Job Search 2016. Ultimately, though, I landed up.

And that is ALL that matters today. Below is the thread on Techwr-L that instigated the brief trip down memory lane.

---

-----Original Message-----
From: Peter Neilson
Sent: Monday, February 20, 2017 8:15 AM
To: techwr-l@lists.techwr-l.com
Subject: Re: Nightmare Library

I've answered this at incredible length in a private note to Zev.
Basically it is attitude and audience. I think that Zev's colleagues believe they are themselves the audience. I also suspect that they are possessed of Ample Attitude.

The problem is akin to writing a popular article about some aspect of mathematics, and showing it to a mathematician. He (the mathematician) will find plenty of things "totally wrong" about what you wrote, as well as finding things wrong with YOU and with your dreadful lack of understanding in mathematics. And that's just for starters. (Done there, been that!)

Attitude Adjustment being inappropriate, the solution devolves to doing an end run, never showing the final version to the SME until it is too late for enemy action. If the SME outranks you substantially, be ready to take a job elsewhere, preferably in an entirely different profession.

> -----Original Message-----
> From: techwr-l-bounces+lynne.wright=kronos.com@lists.techwr-l.com
> [mailto:techwr-l-bounces+lynne.wright=kronos.com@lists.techwr-l.com]
> On Behalf Of Zev Levi
> Sent: February-20-17 2:24 AM
> To: techwr-l
> Subject: Nightmare Library
>
> Hi all,
>
> I work in a country where English is spoken as a second language (if
> at
> all) and I often find myself explaining to product managers and
> developers why their documentation ideas are troublesome. ("Yes, the
> sentence you changed is clear to you but, as it's now five lines long,
> it is confusing to readers. We must explain ideas using shorter
> sentences.")
>
> Is anyone aware of a virtual library of bad-documentation examples (a
> library of tech-doc nightmares)? I'd like to search for *long
> sentences* and find examples of unclear documentation.
>
> It would be easier to convince PMs of writing guidelines if they tried
> reading a doc that didn't follow them.
>
> I haven't had any luck googling these terms; I'm looking for
> documentation examples and google generally returns links to forums.
>
> Cheers
>
> Zev

Finding Remote Technical Writing Gigs

Tip from Will Husa, a Technical Writer on the Techwr-L list:

For obtaining remote work, I've had a fair amount of success with upwork.com. Basically, you bid for projects.

How to Give and Ask for Advice

I try to shoot straight about my career as a technical writer. After 8014 days (21 years, 11 months, 1 week, 2 days), I like to think I know something. I also have learned that if I sugarcoat my experience and only talk about rose petals, thereby ignoring the thorns, who is going to learn? My answer would be "no one." Thus, when I saw this post on the Techwr-L list today, I was compelled to write back:

---

At my current company, the product management team's vision for the next generation of their products is to eliminate end-user UI usage documentation entirely and provide contextual in-product help using video walkthrough tools such as walk.me.
To make a case for using video as an additional learning resource instead of a replacement for context-sensitive UI Help, I'm looking for information on the percentages of technology users who are visual, textual, auditory, and kinesthetic learners.
Case studies of companies who went to a pure-video documentation model and found that their support calls went up and user satisfaction went down would also be useful.
Any suggestions?

---

I went through this @ my previous employer. We had distributed PDFs for our "current" product but for the "next generation" product, we moved to Confluence. Our manager used this as an opportunity to ditch the things she didn't like in the user guide and declared the following guiding principles for the "next" generation documentation:

1. Write system – not role-based, not custom configured – documentation - even though the "current" product user guides were written for a specific level of user
2. Don’t write the obvious which were defined as “no step-by-step instructions” and “don’t use the name of any UI object in the doc” because anything the user saw in the UI was to be considered “obvious.” - even though the "current" product user guides had step-by-step instructions and references to the UI.
3. No screenshots - as in NONE, even though the "current" product user guides had screen shots when it was appropriate to ensure the user had the right information.
4. No PDF - as in NONE, and everyone will be instructed to use the online Confluence site because as soon as you publish a PDF, it is obsolete.

None of those guiding principles flew. The first customer to see "the next generation user guide" wanted terminology to be changed to match the way the system was customized for them (some customers called a thing "groups" while other customers called them "classes" and the "group" customer didn't want to see "class" because it didn't match their system), they wanted step-by-step instructions, they wanted screenshots, and they wanted to be able to print the whole thing by distributing a PDF.

Ultimately, after stating over and over (and over) again that we would use those 4 guiding principles, we caved on all of them and gave the customer what they wanted. I can tell you that no amount of discussion about what the customer had currently made a difference - it wasn't up for negotiation.

Thus, if your product managers are bound and determined to go their route, go with it. Just remember that if a menu and/or screen that is shown in 10 videos changes, you may have to re-record 10 videos and, on top of that, you will not have an easy way to track which videos do actually need to be changed without watching them (unless you have detailed video scripts with the names of the screens documented in those scripts).

Good luck!

---

It's also important to know when to ask for help and to know when the answer you receive is all you're going to get. It's how you ask for help that makes you a better person and believe me, I've asked for help a gazillion times over the years. I have learned that when the person on the other end of the conversation is giving you the hint that you're a pest, you stop writing to that person. This is the email conversation I had yesterday:

---

From: A Website for Word Tools
Sent: Wednesday, January 18, 2017 8:06 AM
To: Me
Subject: RE: Quick Question (I Hope!)
Hi,
In order to find information, I would need to Google too and to examine the found results before I could reply. That was what I did in relation to my first reply too. Therefore, it always takes time even if I may be able to find useful results faster than many. I never just grab a link without checking. Even if I have huge amounts of links but I have to dig deep into my material to make sure I find the most relevant in the situation. Sometimes/often, I could write code faster than finding and checking other people’s code  - but since many people want my assistance, I can’t.
Best regards

---

From: Me
Sent: 18. januar 2017 14:59
To: A Website for Word Tools
Subject: RE: Quick Question (I Hope!)
I understood your statement about not having time to “provide personal assistance for free) and didn’t mean to imply I was asking you to code what I needed! I had just found the first link helpful and was asking if you had a second link handy in your Favorites. I can google - no problem.
Thank you for writing back.

---

From: A Website for Word Tools
Sent: Wednesday, January 18, 2017 7:33 AM
To: Me
Subject: RE: Quick Question (I Hope!)
It is possible to tweak the macro. Please search the internet for solutions. Even if I wanted to, I do not have the time to provide personal assistance for free (as also stated on my website - but I provided assistance in the first place anyway ;-)).
Best regards

---

From: Me
Sent: 18. januar 2017 14:23
To: A Website for Word Tools
Subject: RE: RE: Quick Question (I Hope!)
Thanks for the link! I was able to get that macro to work. It doesn’t help me with the “Body Text Indent, DRM_P_Body Text Indent, HCIS_P_BodyTextIndent” style, though. The constant is that the styles begin with “DRM_” and if it’s in the middle of the style, there’s a comma (,) between the next name.
Do you have a resource that you could point me to get rid of the “DRM_*” style when it’s in the middle?

---

From: A Website for Word Tools
Sent: Tuesday, January 17, 2017 3:05 PM
To: Me
Subject: RE: Quick Question (I Hope!)
You need a macro. Google “VBA word rename styles” or something like that.
Example: https://www.experts-exchange.com/questions/22494609/word-vba-need-to-rename-a-set-styles.html

---

From: Me
Sent: 17. januar 2017 21:37
To: A Website for Word Tools
Subject: Quick Question (I Hope!)
I have styles that are named like this:

How do I find all instances of styles that have "DRM_ " in the name of the style and replace it with “HCIS_”?
Me

---

I think the person on the other end of the email conversation was helpful.

Examples of Poorly Written Instruction Manuals

There was a thread on Techwr-L that included a link to "examples of poorly written instruction manuals" and it led to a brief excursion into the underbelly of my profession. Here are some of the links I looked at:

1. Examples of Poorly Written Instruction Manuals
2. http://cdn.ifixit.org/files/2012/04/comcastremote.jpg
3. http://ifixit.org/blog/2251/5-ways-manuals-suck-more-than-root-canals/ 
4. http://www.forbes.com/sites/nextavenue/2012/10/31/how-to-cope-with-useless-user-manuals/#62eba8983a26
5. http://byu316.blogspot.com/2012/07/examples-of-goodbad-instructions.html 

Disservice

From the Techwr-L list today:
On Mon, Oct 24, 2016 at 7:47 AM, Lin Sims wrote:
> Was everyone but me aware that if you create a shared review pdf using
> the Standard version of Acrobat that the reviewers must ALSO have the
> full Acrobat? I seem to have missed that little tidbit, and my users
> have been very frustrated when trying to use a shared review when all


Robert Lauriston replied:
Yes. Adobe does its customers a disservice by not mentioning that in every relevant help topic.

https://helpx.adobe.com/acrobat/using/preparing-pdf-review.html

We Don't Need You

No one needs a technical writer. After all, all we do is write. Anyone can write. The argument that you must have a college degree in English to be a technical writer is absolute hogwash. I do, but it's never been something I thought I had to have in order to be employed as a technical writer. I base that idea upon the premise that members of the Techwr-L list work as a technical writer and, per a recent thread, many of them do not have a college degree in English.

After all, the ability to point out what is wrong with this graphic has nothing to do with my English degree. Rather, it has to do with an eye for detail.

When Does it End

My day started with this post on the Techwr-l list:

|

Subject: Politically correct term for four-eyes authorization?

Hi,

We have a problem with a term in our product documentation (and the UI as well), and I'd like to ask for your collective wisdom.

In line with the four-eyes principle, our product can require an authorizer to approve (and possibly review) the actions of a user. Currently, this is dubbed four-eyes authorization. The problem is that the "4-eyes" term is derogatory and should be changed. Possible candidates we found and are commonly used are "dual control" and "two-person rule", but these are not as accurate, because in every definition I could find (for example, http://www.theserverside.com/report/Integration-of-User-Control-Mechanisms-into-Secure-Critical-Applications), they refer to two users who have the same privileges to perform an action, but can only do so together. In our setup, this is not the case, one of the users is who performs the action, and the other approves that.

If any of you works in an IT security or finance-related field, have you encountered a problem with four-eyes before? (And how did you solve it?)

Thanks a lot for your ideas in advance.

|  

Off-list, I responded with this:

|

I don't accept your conclusion that "4-eyes" is derogatory. I've been called "4-eyes" on occasion when someone refers to me wearing glasses. If anything, I don't think it's accurate as I wear glasses so, by the definition that "4-eyes" means someone with glasses, I wouldn't think I needed a second person. Is there a reason you have to call it "anything" at all and simply focus on naming the task the user is doing with your product. Something like "Obtain Authorization from a Second User."

We have something in the system I work on now where a person reviews a response to an essay and then assigns a score, based upon established criteria and project rules. The response to the essay is then routed to another user and that person reviews the same response and then assigns a score. If the scores are the same, all is good. If the scores are different, they go to another person who reviews the response and assigns a score. That third person who assigns a score is "adjudicating" the assigned score. The name of that task is, yep, " Add an Additional Score for Adjudication of Score Differences."

Good luck.

[rant: I'm saying all of this because I went through something similar years ago while working at a telecommunications billing software company. I was talking to the lead designer about a project that would add two types of the same entity to the system. One was going to be the highest level and was to be called "master" and the term for its subordinates? Yep, "slaves". The lead designer said, "We can't have 'master' and 'slave' in our system!" I said, "Why?" "Because it could offend someone!" "Does our system have anything to do with the Civil War?" "No. " "So why would you apply terms that are most commonly associated with the Civil War to our system?" My point was that "master" and "slave" in our system had nothing to do with the despicable legacy that caused the Civil War. It is a term that is used in the IT industry and our use of it, in the IT industry, was appropriate. Lately, it's getting worse. Society is just getting too crazy with what you can say and what you can't say. For example, if you work at a specific company and say, "you guys", you now have to put $1 in a jar because "you guys" is sexist. Another example is if you describe someone that robs someone else as a 'thug' it's now considered a racist term. One time I mentioned that "the office girls" were making copies for me of a user manual only to be called out for that phrase because it was "sexist." Finally, and this is more about the dumbing down of our society, if you attend college at Utah Valley, there's now a third lane in some areas on the sidewalk. One is labeled "walk" one is "run" the third is "text", which is for those walkers that are texting as they walk. Someday we will have no way to communicate because all words and even actions will be deemed inappropriate because they will offend "someone" in some way. It has to end somehow. [/rant]

Sorry if this rant offends you but I thought it might best describe my perspective.