Technical Writers: The Unsung Heroes of Customer Experience

Lately, I don't really think about "technical writing" as an industry nearly as much as in days past. I can cite the reality that, in 2023, I didn't create a post with the "Technical Writing" label until Tuesday, March 14, 2023, and that post was simply a link to elsewhere - https://prhmusic.blogspot.com/2023/03/blog-post.html - with zero words written by me. I'm unsure why this is the case as I still go to work and when I arrive, I am a Senior Technical Writer - that is still my title and that is still my role. Maybe that is why the article below made me revisit this idea that I have had in my head for quite a while, which is to explain that yes, my title and role is that of a Senior Technical Writer, but no, I do not do the work of a traditional Senior Technical Writer. I consider the traditional role of a Senior Technical Writer to be the role of learning a subject area to the degree that documentation about that subject area can be written. I don't do that. I consider myself to be more of a Documentation Assembler. For the 3 major projects with which I am involved, I rely on other co-workers to write documentation and then, in some instances, I may proofread the content, but in 90% of the work I do, I don't even proofread or edit the content. Literally, I assemble the work of others into a cohesive presentation of the content that is then distributed. That statement is true for 

1. The Disaster Recovery documentation project
2. The Knowledge Management project
3. The Operations Manual project

I'm not complaining as the way I do my work is aligned with what I like to do. I like to write DOS batch files in a folder with 

            81126 File(s) 43,575,880,874 bytes
            7655 Dir(s)  349,230,120,960 bytes free  

and eliminate a bunch of files until there are only 8379 files with only the following file types:

*.mp4, *.docx, *.doc, *.zip, *.xps, *.xml, *.xltx, *.xlsx, *.xlsm, *.xls, *.vss, *.vsdx, *.vsdm, *.vsd, *.vdx, *.txt, *.pub, *.pptx, *.ppt, *.png, *.pdf, *.onetoc2, *.one, *.msg, *.jpg, *.jpeg, *.csv

I doubt many Senior Technical Writers are like me.

In any case, read the following article about how Technical Writers are the unsung heroes of customer experience.

---

https://thecontentwrangler.substack.com/p/technical-writers-the-unsung-heroes-bae?utm_source=post-email-title&publication_id=1587018&post_id=135611902&isFreemail=true&utm_medium=email - Technical Writers: The Unsung Heroes of Customer Experience

---

Searching for a Snare Drum stand, not Frustration

I wanted to buy a new snare drum stand. I went to West Music and searched for snare drum stand and got some results.

When I selected the snare drum stand that I circled in red, I learned that it was out-of-stock at the Coralville store. 

 

Because I am a male Karen, I sent the "Store Manager" the following email:

When using your website, it’d be nice to be able to filter by both store and by “stock status.” I am looking for a snare drum stand so I searched for it and saw this. However, when I selected the Mapex stand, it was only then when I found out that it’s not in stock at the Coralville store. It’d be a better user experience to be able to sort by both store & stock status. Thank you.

Adobe Issue

 On my work laptop, I seem to be having an issue with Adobe IDs. I have one Adobe ID for RoboHelp and a separate Adobe ID for Adobe Creative Cloud. It appears that I can't use two distinct Adobe IDs on the same laptop, even though I have been doing so for quite some time. I think the main difference is that I didn't have a newer version of RoboHelp installed on my laptop until recently. In any case, one of my pet peeves, when it comes to laptops and the user interface, is when I see a message that is incorrect. Case in point, I don't have Photoshop open - I have Dreamweaver open - and the message I see tells me to close Photoshop. I often try to put myself in the role of a user who is not as ... 

I consider myself a dangerous user when I use a laptop or computer. I can trace using a computer back several decades when a family friend, who worked for [redacted] let us use a computer at our house. It had two 5 1/4" floppy drives - that's how long ago I can trace back my computer usage. Later, there was a computer with a 3.5" disk drive in the house. 

My point is that someone who does not have as long of a history with computers could likely become very confused when seeing a message to close a program that is not open to resolve an issue. I recognize the message as a specific message being used in the incorrect circumstance. Obviously, the message should say Close this window to quit Dreamweaver instead of Close this window to quit Photoshop because I do not have Photoshop open. 

Actually, a better message would be Close this window to quit the Creative Cloud app that you were using when this message displayed - even if it is wordy.

Click the Clean CSS button - except it doesn't exist!

 

Updated a Previous Post

Unintentionally, I found myself diving into this post a bit deeper...

Best Online Help You Have Seen

1. These Are Nice and they were created with Confluence...
2. https://docs.memsql.com/
3. https://github.com/PharkMillups/beautiful-docs
4. http://www.circularlabs.com/documentation2/documentation.html - I enjoyed reading this:
• Be warned that Mobius is a complex program with an enormous number of options. Many people say that it is "too complicated", the user interface is "ugly", and the documentation is "boring". All of these are true. If you are looking for a DL-4 emulator with photo realistic knobs you can just plug in and play then look elsewhere. If you are looking for a new musical instrument you can customize to work the way you want it to, then you've come to the right place. Just be prepared to do some reading and ask a lot of questions.
5. http://linlaurie.com/portfolio1/
   

Okay and this Means What Exactly...

Today, I was confronted with this message when I logged in to Blogger:

---

---

"What the hell is OpenID?!?" I was curious and so I clicked the Learn More link.

Big mistake!

---

I saw this page:

---

---

In theory, I realize this page https://productforums.google.com/forum/#!topic/blogger/Wuem4GoXYXo likely was created to offer hope to users like me who want to read information about OpenID but that theory is severely lacking in execution since I still have no idea what OpenID means to me specifically.

Apparently, I'm not alone, judging by this comment:

---

---

I also clicked the Google Takeout link, hoping to read more about it, but I had to click another link to end up here https://support.google.com/accounts/answer/3024190?hl=en so I clicked Back. I noticed a Blogger section. I have multiple blogs on Blogger but this is the only one I update regularly so I saw no sense in backing up all of my blogs. I selected the Select blogs option button.

---

---

When I clicked Blogs to select this specific blog, I saw this unhelpful window instead of a list of my blogs:

---

---

I get how Google has the world by the balls as far as being the number one thing going on in technology, but given my interactions with their site today, it's clear to me they are lacking in user experience expertise.

Pretty Sure I Covered This Type of Issue Elsewhere in the Maze of 6000 Posts.. But it Still Makes Me Smile

I do not have intimate knowledge of the job role who created the help text on my electric company's website. When I paid my electric bill today, I clicked the Help link and saw what you see to the left. For the sake of this post, I am assuming a technical writer wrote the help text you see.

That said, I do not understand how that technical writer can allow it to exist on the company's public website. It makes me think that either that technical writer doesn't work for the company or doesn't know how to fix it.

I'll hope for the first option, but suspect the second.

This is what I see:

1. The purple rectangles are fine. 
2. The red rectangles indicate that there is not a definition for
   ol li li that has indentation.
3. The green rectangle indicates that there is likely an ul instead of a ol under the "Update Stored Account" heading.

For me, it would be a very simple job to fix the HTML code.

What I wonder about is whether that technical writer even viewed their code in a browser prior to publishing it or routing it to someone else to publish it. In either scenario, the HTML code is wrong. 

Well, first of all, the HTML code of that page is absolutely hideous! No one should be using [b][i]Title[/i][/b] instead of a h (heading style). If you look really close, you'll notice that instead of putting the "heading" in a p (paragraph) tag, the author used a br (break) tag to achieve the desired formatting. It's very ugly.

I learned HTML on my own by reading various websites and investigation of cool-looking websites. When I was trying to learn all about WinHelp files, first, I would seek out WinHelp files that I could download, and second, I would use the Help Workshop .exe file and decompile the WinHelp file and then look at how to incorporate what the Technical Writer did originally. I applied that same type of logic to when I was tasked with writing the help text in HTML pages for a system called "EBPP" which may or may not even exist. I had to figure out what to do on my own and, to do that, I downloaded many HTML pages with really cool visuals that I wanted to incorporate. I took that ugly source code and dumped it into Dreamweaver, then cleaned up the code. Of course I think my cleaned up web page is much better than the original.

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.

Why Microsoft Gets a Bad Rap for their Online Help

First, a picture, then an explanation.

---

---

Now what did you just look at in the above picture?

1. I wanted to delete a style.
2. I saw an error message with a Help button. I clicked Help
3. I see the Word Help window and instead of showing me information even remotely related to styles, the window includes the text Results for "", which indicates that there was no parameter passed from the Help button to the help system. Thus, the first result I see in the list has NOTHING to do with deleting a style!

That is so wrong and why I, as a technical writer, can't justify a suggestion about how to access Knowledge Articles through our instance of Cherwell because I don't want to follow "the Microsoft standard" due to seeing shit like this!

Down the Lane

I read this article - Sympathy Card to a Front-End Developer By Carla Pileggi October 9, 2017 - twice.

The first time, I thought about the low-hanging fruit. Immediately, the story was relevant to my days at Quintrex, the company I worked at from 10/1/1998 to 10/15/2010. The article tells a story about a grieving developer as his beloved system's user interface was being redesigned by the author. At Quintrex, there was a point during those 12 years when our systems had been developed in multiple programming languages and by multiple teams. There was not a single "Quintrex" look and feel. There were rules for using the systems and those rules were dictated by the programming language / team, not by Quintrex, the company. At some point, the decision was made that all of our systems would be converted to (yet another) programming language. It was kind of a running joke. There was always an effort to rewrite the systems in a single programming language and the list of the "chosen" or "standard" programming language was changed several times over the years.

At one point, there was a meeting I attended. The reason I remember this specific meeting is because it was very tense. None of the teams wanted to concede anything about their workflow because, and I get this, their workflow made sense to them and the thought of re-learning the way they did their job was scary. The meeting was riddled with a lot of subtle (and sometimes not subtle) statements, such as these:

---

Your system in your programming language looks bad.
My system in my programming language looks awesome.
As a company, we should adopt the way my team do things.
The way my team does things should be the new standard.
All you other teams should have changed your standards to match mine years ago
No, of course I don't have my team's standards in a document that you can read - we know how to do our job!

---

Of course, no, no one actually said those exact words, but there would have been a higher degree of honesty in the room if someone had actually just said those words.

Recalling that meeting in my brain was intriguing so I reread the article. This time, though, I extracted the Developer reaction text from the article into this blog post. Originally, my idea was to use them as a springboard for writing this post. I thought this post would be summarizing the meeting above only. But then something made me think about something else. But before I get to that, here are the stages from the article:

---

Stage I: Denial

Upon seeing the new sketches, the developer’s first reaction was to deny the reality of the situation.
Developer: “I’m sorry, I don’t think you can even do that in HTML. Errr, no, no…. Technically, this just can’t be done. Sorry.”

Stage II: Anger

Developer: “This is wrong—all wrong. You don’t understand this product. I do. Our users won’t like this. Stop sketching and listen to me! Have you worked on this type of application before? These designs are ridiculous! Why aren’t you listening to me?”

Stage III: Bargaining

Developer: “Um, your colors…. Your colors are good. Let’s just take your colors and put them on the existing user interface. Then, can’t we just leave everything else alone?”

Stage IV: Depression

Developer: “You know, I never really cared about what the user interface looked like anyway.”

Stage V: Acceptance

Developer: “Do all of the new product designs have to be implemented in this release?”

---

As I mentioned, the article is presented in the context of a Developer grieving over the changes to a product he brought to life. As I reread the article, I applied my 20+ years of working perspective, I can apply the Developer's grief to my own work as a technical writer when there is a transition. Over the course of my career as a technical writer, I have gone through many transitions. I will name only one at each employer, but, especially at Quintrex, I went through many transitions:

1. NDP: converting from using OfficeVision to write training documentation to using MS Word
2. JSI: transitioning from being a 'stand-alone' silo-type operation to consolidating each person's information / knowledge into a central repository.
3. QDS: transitioning from documentation being a 'stand-alone' silo-type operation where each Quality Assurance tester wrote or updated documentation to developing a workflow where I was to review the changes to the system and figure out what documentation needed to be changed.
4. Unnamed Hellhole in southern Iowa: honestly, bringing me into the department and having me question the tools we used (InDesign) was a big transition. Also, since I was to focus on creating online Help, that was a very different mindset.
5. Pearson: converting from using MS Word and distributing user guides as PDFs to using Confluence
6. Where I am now: transitioning from being a 'stand-alone' silo-type operation to consolidating each person's information / knowledge into a central repository so that I can publish consolidated disaster recovery documentation

Each of the above transitions had pain points that deeply impacted me as a person as well as me as a technical writer. I credit Carla Pileggi with giving me a new way to look at my past.