How is this Done?

For decades, I have been curious about the technology I encounter daily. 

This dates back to at least 2005. My curiosity led me to receive the RoboHelp MVP award for answering questions in the Adobe forums. I point to the fact that I would seek out WinHelp (.hlp) files. If I saw something I wanted to implement into my WinHelp files at work, I would download the WinHelp (.hlp) file - many times to my PC at home at my leisure (off-work) and then decompile the .hlp file in order to figure out how the original technical writer implemented the cool thing I wanted to implement in my WinHelp files at work. At the time, I was working with a master.cnt layout of connecting 100+ WinHelp files seamlessly into what looked like a single WinHelp file. It was truly awesome. 

So that's the background for why I was looking at this email I received this morning. I spent a couple of minutes drawing lines from the email preview on the left to the corresponding text on the right. The question is: where is the text in green on the right side? My best guess is that there's text in the HTML code, somewhere, that shows that text in the green box on the left, but not on the right. Maybe? I do not know...

---

---

MS Word, includetext, and templates

Editor's Note: The link to http://www.paulpehrson.com/flare-content-reuse/ needs to be tested.
Five years ago today, I posted the following on Techwr-L:

On 4/7/2015 1:01 PM, I wrote:

I am so JEALOUS! Over the 20+ years of my career, conversions - whether it
was OfficeVision to Word, WinHelp to HTML, or Word to Confluence - have been
my favorite projects. Even outside of work, I love converting - CDs to MP3,
vinyl to MP3, and cassettes to MP3. Conversions are my passion!

Recently, we've transitioned from authoring in Word and distributing PDFs to
using Confluence. I did not know anything about Confluence until I started
trying to maintain content in it.

One thing I think is worth considering - are your users going to "accept"
your docs on a wiki? We jumped into it, internally reviewed it (within our
dept & and within the company), gave it to the end-users and the first thing
they said? "How do I print a PDF of all the pages?"

<sigh>

We had to add a process for creating a PDF of the user guide that is posted
on our Home page. We make it clear that the PDF is a snapshot of the content
as of MM/DD/YY and that it is going to be quickly out of date if you print
the thing.

All that said, if you suspect you have multiple versions of the same text,
what I messed around with was creating a single (somewhat massive) Word doc
with all the Word doc content in it.

However, before I could do that, I took a copy of each document and replaced
the paragraph character with "- [unique_code]" so that when that document is
combined with all the other Word docs, you know where it came from. For
example, we have a "Adding a User" heading in all of our docs. If you
*don't* add a unique code to each paragraph, you get this:

Adding a User
Adding a User
Adding a User
Adding a User
Adding a User

And you don't know where they came from. For us, states are a good way to
group things so I had:

Adding a User - AZ
Adding a User- CO
Adding a User- FL
Adding a User- TX
Adding a User- VA

So, after you have that pre-processing done, combine the docs into a single
Word doc, because ultimately, what you want is something like this:

Adding a User - AZ
Adding a User- CO
Adding a User- FL
Adding a User- TX
Adding a User- VA
Changing a User - AZ
Changing a User - CO
Changing a User - FL
Changing a User - TX
Changing a User - VA

Then, you create a single version of your procedure, looking at how each
version is different. If there's something customer-specific, then you make
a note of that, but the end result is a single way you are going to tell
your users how to "add a user", how to "change a user", etc.

Then, and only then, do you begin thinking about include fields and such.
Otherwise, you are going to have very similar fields that have only slight
variations that are used for specific customers, but not a single "include"
for all of your docs.

That said, I came across this page the other day -
http://www.paulpehrson.com/flare-content-reuse/ - that may be helpful. It's
older (2007), but some of the philosophy behind it (not the Flare-specific
things] may help you out.



-----Original Message-----
From: Jay Maechtlen
Sent: Tuesday, April 07, 2015 1:19 PM
To: TechWrl list
Subject: MS Word, includetext, and templates

We're using Office 2013 on Windows 7, deployment planned on SharePoint.

1) Anyone using includetext fields to consolidate multiple Word docs? Any comments on best practices, templates, styles, etc?

2) Anyone deploying on SharePoint Wiki sites? We intend to move docs to the Wiki, but building in Word until the Wiki is really ready. (and/or we know how to use it well enough.)

Current docs are combination of Word and Excel docs.

Comments, suggestions welcome.
Thanks
Jay

--
Jay Maechtlen
626 444-5112 office
626 840-8875 cell
www.laserpubs.com

Trip to the Past

I came across this page - http://www.adamarnold.net/lshhlp/ - and wow, that is SO cool that there is a WinHelp file about the Legion of Super Heroes. I offered to convert the WinHelp file to a CHM file, using RoboHelp. I don't know if the owner of the page wants a CHM file, but I'm excited about dipping my toe back into a file format I used extensively in my career as a technical writer.

Not a CSS Expert But... This isn't Right, Right?

I am 100% self-taught when it comes to HTML, CSS, RoboHelp, DOS, Excel, Confluence, and JavaScript. I have learned what I know from reading and trying to adapt what I read for my own purposes. I know I've mentioned that when I was learning about WinHelp (.hlp) files, I would download pretty much any WinHelp file I could find. After I opened the file on my computer, if I saw something I wanted to do in the WinHelp files I was creating at work, I would de-compile the file and look at how the author had created a button or some other feature. I was thirsty for knowledge. The same thing has plagued me during the years since working with WinHelp files for other technologies. I frequently look at CSS files and try to understand what is included within the CSS file to produce a specific characteristic of a website.

Today, I found something that doesn't make sense to me.

---

---

Defining h3 (Heading 3) twice in the same file seems wrong.

Editor's Note: Added the "WinHelp" tag for this post. 

Update: CSS is read from top to bottom, per https://stackoverflow.com/questions/25105736/what-is-the-order-of-precedence-for-css.

Lesson 2016:03

When I left Pearson for the last time as an employee on January 26, 2016, which was 11 months, 5 days (340 days) ago - the day I was laid off - I cared about Pearson documentation.

I still care.

However, I have learned (a-ha!) that I can not control what my co-workers do with the documentation I helped create. I am no longer their co-worker. Yes, I will likely have a morbid curiosity for a period of time. I had that same type of attitude when I could view the Quintrex documentation after I left. Eventually, though, that feeling of ownership dwindles as the balance between what I contributed and what has been contributed since I left tips.

Quintrex? Ah, yes.

When I left Quintrex on October 15, 2010, it was leaving 12 years, 2 weeks (4397 days) of work behind.

I had an empire. I was the only technical writer and every word that went into the online Help, which was seen by the customer, and every word that went into the internal documentation was reviewed by me.

The end-user documentation had started as hundreds of OfficeVision (an AS/400 word processor) documents and a handful of MS Word documents. Over my time there, I had converted that content to WinHelp files (see below) and then to HTML. I can vividly recall that I knew about "span classes" when I initially started working with HTML. I created a CSS definition called "programname" and any time I wanted to have bold, I used that span class. Then I learned about having a separate CSS definition for each "type" of "thing" I wanted to be bold. I defined "check_box" and "dropDown" and "dropDownValue" and was methodically going through all of my HTML files to change "programname" to a specific span class tag. That work was not done when I left.

The internal documentation was called Billopti. That was short for "Billable Options" even though I referred to them as "System Options" in the documentation. Why the difference? In reality, not all "Billable Options" were actually billable to the customer. Some "Billable Options" were standard.

I digress.

When I left Quintrex on October 15, 2010, I really thought I was going to a better situation. I thought I would be able to build the same type of pseudo-kingdom I had built at Quintrex. I thought I was going to do awesome but readers of this blog from October 15, 2010 - April 15, 2011, know the truth.

I digress again. Damnit!

When I left Quintrex on October 15, 2010, I had invested hours upon hours of my own time to learn technologies. I spent hours in the den, downloading WinHelp (.hlp) files and decompiling them to learn how a feature I had seen was done. If it was fairly easy, I would then take that knowledge to work the next day and try to implement it.

When I left Pearson January 26, 2016, I had been with the company for 4 years, 7 months, 3 weeks, 5 days (1701 days), which is obviously not as long as the amount of time I was at Quintrex. Yet, with the Pearson documentation, I really came into a deeper sense of my work. When we shifted from the PDF paradigm to the Wiki paradigm, I was initially not a strong supporter. I knew our existing customers and my co-workers had very specific requirements and I was doubtful they could be met with a Wiki. Initially, the direction was to dismiss those requirements and to not worry about:

1. writing procedures - we would lead the user to the place in the system to do a task but not tell them what to click
2. writing user-role based documentation - we would document all tasks that could be done in the system
3. including screenshots - we would not include screenshots for a variety of reasons
4. creating a printable version - we would not create a PDF because a PDF is instantly out-of-date

Our department had worked in that direction until we showed it to the first customer of the rewritten system. Guess what they wanted? Better, guess what we began to do...

But This is Even MORE Amazing

Submitted when a window popped up, asking for my feedback about the RoboHelp forums:

---

I have been a RH user from 10/1/98 - 10/1/2010 and now, from 3/29/16 - today.

I am VERY HAPPY that a request to provide forum feedback popped up. Please review https://forums.adobe.com/message/9119988#9119988

The summary is this:

On Friday AM, Adobe Tech Support posted that a fix had been released for an issue I am having, but there was no location specified to download it.

By the time I went home on Friday afternoon, there was still no fix posted.

On Monday AM, Adobe Tech Support AGAIN posted that the fix had been released. However, no download. I have been checking http://www.adobe.com/support/robohelp/downloads.html routinely.

Though, frankly, that is a joke that I find almost repulsive because the "Top Support Topics" are for "RoboHelp 7"?!? I was using RH 7 when I left a company in 2010 to go to another company!!! Additionally, all of these links are broken in the "RoboHelp Downloads" section:
|
Service Releases
-->        FlashHelp Files
-->        WebHelp Pro Files
-->        WebHelp Files
-->        HTML Help Files
-->        WinHelp Files
-->        JavaHelp Files
-->        RoboLinker Files
-->    Miscellaneous Files
RoboHelp Documentation
|

I'm very frustrated, almost to the extent that I am very much regretting that I chose RH over Flare as the HAT to use.

My hope is that maybe SOMEONE will read this and DO something my issue!!

Again, this is all in reference to this thread in the forums:
https://forums.adobe.com/message/9119988#9119988

Help me anonymous reader of this feedback, you are my only hope.

---

WinHelp Revisited

I am going through a directory full of DOS batch files and deleting files that are no longer necessary.

I just came across one, with a modified date of 7/11/2004. Before pasting the contents of the file below, 2004 was perhaps the height of the time I have spent in my career with WinHelp. I became somewhat accustomed to the use of DOS batch files as a way to manipulate files and their location. When I found out that I could write a DOS batch file that would compile my 100 WinHelp files - instead of spending a lot of time - 100 projects x 5 minutes each = 500 minutes divided by 60 minutes in an hour would mean 8.33 hours required to compile my projects - a day at work. Thus, by writing a DOS batch file, I drastically cut down on the time that I needed to devote to that task.

At home, I was creating multiple WinHelp projects for my personal use. I was preoccupied with the WinHelp file format; I thought it was the coolest thing I had ever seen in my life. I had a lot of content to organize and the following files were how I did that. Unfortunately, I do not think I have a backup of these personal projects anymore - they were on a hard drive that I can no longer access. I spent many hours creating the following files:

1. Glossary.hlp, for storing information about various people in my life.
2. Career.hlp, for storing information about my career.
3. Jokes.hlp, for storing various funny jokes and cartoons.
4. 200 Days.hlp. The 200 Days journal series has 4 volumes. 
1. Volume I - the 200 days prior to our wedding day on 8/7/93
2. Volume II - the 200 days prior to our first wedding day on 8/7/94 
3. Volume III - the 200 days prior to our first wedding day on 8/7/95
4. Volume IV - the 200 days prior to our 20th wedding day on 8/7/13 (for the record, WinHelp was a dead technology before I reached my 20 year anniversary of being married)
5. Music.hlp, for storing music reviews, concert reviews, and anything related to music.
6. Essays.hlp, for storing any essays I was writing at the time.
7. Songs.hlp, for storing the 18 volumes of songs and lyrics I had created in spiral notebooks and then transcribed.
8. Email.hlp, for storing emails (which were new at the time) in a consolidated place.
9. Wrkjrnl.hlp, for storing information related to my career, but specific to my employer(s) that were either current or recent.
10. prhmusic_master.hlp. This was what was referred to as a "master" project. Its purpose was to maintain links to the other .hlp files. This was the file that was opened in order to view the other 9 files - I know I had a shortcut to it so I could access it quickly.

So here are the contents of the DOS batch file that I used to compile my personal projects.

---

cd\
cd C:\Progra~1\RoboHe~1\Compil~1\WinHelp\
hcrtf c:\prhmusic\glossary\glossary.hpj
hcrtf c:\prhmusic\career\career2.hpj
hcrtf c:\prhmusic\jokes\jokes.hpj
hcrtf c:\prhmusic\200_Days(all)\200days.hpj
hcrtf C:\Prhmusic\music\music.hpj
hcrtf c:\prhmusic\essays\essays.hpj
hcrtf C:\Prhmusic\songs\songs.hpj
hcrtf c:\prhmusic\email\email.hpj
hcrtf c:\prhmusic\master\prhmusic_master.hpj
hcrtf c:\prhmusic\career\wrkjrnl.hpj
REM | After compiling, copy the .hlp and .cnt to c:\prhmusic so it can be accessed.
copy c:\prhmusic\200_Days(all)\200days.hlp c:\prhmusic
copy c:\prhmusic\200_Days(all)\200days.cnt c:\prhmusic
copy c:\prhmusic\career\career2.hlp c:\prhmusic
copy c:\prhmusic\career\career2.cnt c:\prhmusic
copy c:\prhmusic\email\email.hlp c:\prhmusic
copy c:\prhmusic\email\email.cnt c:\prhmusic
copy c:\prhmusic\essays\essays.hlp c:\prhmusic
copy c:\prhmusic\essays\essays.cnt c:\prhmusic
copy c:\prhmusic\glossary\glossary.hlp c:\prhmusic
copy c:\prhmusic\glossary\glossary.cnt c:\prhmusic
copy c:\prhmusic\jokes\jokes.hlp c:\prhmusic
copy c:\prhmusic\jokes\jokes.cnt c:\prhmusic
copy c:\prhmusic\master\prhmusic_master.hlp c:\prhmusic
copy c:\prhmusic\master\prhmusic_master.cnt c:\prhmusic
copy c:\prhmusic\music\music.hlp c:\prhmusic
copy c:\prhmusic\music\music.cnt c:\prhmusic
copy c:\prhmusic\songs\songs.hlp c:\prhmusic
copy c:\prhmusic\songs\songs.cnt c:\prhmusic
copy c:\prhmusic\email\email.hlp c:\prhmusic
copy c:\prhmusic\email\email.cnt c:\prhmusic
copy c:\prhmusic\career\wrkjrnl.hlp c:\prhmusic
copy c:\prhmusic\career\wrkjrnl.cnt c:\prhmusic

---

Backups and the Need for Them

I want to be clear - I'm still happy at my employer. More about that in a few moments.

I'm quite certain I didn't know that the airplanes in our skies are controlled by 40 year old technology. This article begins with the story of an air traffic worker who wanted to create a disruption so he set a fire and cut cables, with the forethought that a backup system would then take over. The worker had been an employee for 8 years and didn't know that there wasn't a backup.

It's ironic that I read this article today because I learned yesterday that while I had assumed there was a backup for our documentation on our server, there was not. When the server crashed, there wasn't a backup. That sent my day into a wild roller coaster ride. My manager came to me and asked that I compare a list of graphics that my co-workers put together - one for each user guides we post on that server - with a list of graphics that were pulled from the server.

At that point in my day, I think I began working on what I consider to be a strong aspect of myself. I analyzed the two lists, weeded out the duplicates using Excel, got each list into a separate Word doc and used Word's compare functionality to tell me the differences. It was awesome and as close to working on a conversion as I've come in quite a while.

Just for reference, my love for working on conversions is well-documented on this blog. In the past, there's been conversions from OfficeVision to Word, from WinHelp to HTML, from Word to HTML, from CDs to MP3, and from cassettes to MP3. With each of these conversions, I conquer the tools that are available and that, perhaps more than actually writing content, is what I consider to be a character strength. That said, I realize I am a technical writer at my employer; it's never been only tools over the last 20 years and, frankly, I don't expect it ever will be. I'm just stating I love the times / eras in my career when my focus has been on converting the presentation of content from one format to another.

Back to the story, I worked from 7 - 3:30, which is when I went to pick up Alex from school. It's funny to me that I had insisted to Karen that I could pick him up. I had reasoned that I would be heading that direction anyways because I also was going to be going to the Coral Ridge Mall to pick up something after 3:45. It made perfect sense. And yet, as I blasted my way down I-80 to I-380 to head south to Iowa City West, I thought about how on a normal day, without the crisis at work, my insistence would have been no big deal at all. When I told my manager that I had to go pick up Alex, I was doing so at the same time that my co-worker in Texas was going to go pick up her son from school. I was waiting on a list of files from her anyways so it seemed like good timing. I could see something in my manager's eyes, though.

I got Alex picked up and the things at the Coral Ridge Mall picked up without issue. I was home by 4:30ish. We had planned to go to the Saint Thomas More fish fry and in the discussion with Karen about what time we were going to leave, the ultimate decision was to return to work. I was back at my desk ~5 and left the office ~10 PM. I worked 13.5 hours yesterday, but I think it was more than the Mountain Dews and Pepsis I consumed throughout the day that propelled me through the hours I worked.

Notes from Career Panel

I was asked by Mount Mercy University English professor Carol Tyx to be a member of a panel of MMU alumni that were English majors. The purpose of the panel was to discuss our careers. Prior to the panel, Carol emailed me a set of questions and, using those questions as prompts, I created the following content. This is a selfish post, one that specifies a lot of details about myself and my career journey. To prepare for posting my notes to this blog, I did some minor editing just because it's my blog and I can do that since I own the content.

---

Career Panel Thursday Nov. 20 2:00-3:00 109 Warde

What has been your employment journey since graduating from Mt. Mercy?

Context First

I came to Mount Mercy College in fall of 1988. My goal was to be a high school English teacher. I did a semester of Student teaching in Fall 1991. I did not like teaching – stories could be told about being slapped by a student, breaking up a fight, and going through a faith crisis at the same time - what am I doing here on earth? What purpose do I serve?

To summarize, those are the “highlights” of the “Dark Time of my Life” and by the time I graduated in May 1992, I had concluded teaching was not a career for me.

Since I had gone through my college education with a focus on being a teacher, it was difficult when I realized I had no idea what I could do with my degree.

I began my job search in February 1992 and it ended 3 years later in February 1995 and during those 3 years, I applied to many companies for many positions in many cities.

During the time that I didn’t have a permanent, full-time job, many life events:

• Proposed to my wife in June 1992
  
• Married my wife in August of 1993.
  
• We purchased first house in April 1994.
  

Miscellaneous non-technical writer employment

• Telemarketer at APAC
• Temporary data entry clerk at ACT (Iowa City)
  
• Software Quality Assurance Testing at ACT (Iowa City)
  
• Got an awesome letter of recommendation from manager!
  

First Technical Writer position NDP (Cedar Rapids)

Interview at 8 AM on Friday, February 10, 1995 & signed job offer letter before noon. Words of advice: Always negotiate salary. I was offered $17,500, which was low, so I countered up to $18,000. I should have asked for more. The VP I was interviewing with said that I would have to work that much harder for that extra $500.
Two recurring themes in my career:

• Networking 
• The only reason I even knew about this company was through a friend. My wife and I had a New Year’s Eve party on 12/31/1994. Invited several friends (MMC alumni). One friend was having a “good time” and started talking about how he worked for a great company. If he hadn’t been at our house that night, I would have never known of their existence. There was never a job ad for the position I applied for.
• Focus on content. 
• Don’t rewrite or rephrase what someone tells you should be told to the end user. You should be knowledgeable about your subject so that you pick and choose those details that the user needs.

I worked there for 3 years.

Second Job: Jordan Systems

Jordan Systems had a product that was PC-based software, not AS/400.

Do not fail to value networking! Worked with a MMC alumni who lived on my dorm floor my freshman, sophomore, and junior years. Software on an AS/400 with an interface to a PC. AS/400 used to be a popular platform in the area and you could take programming courses at Kirkwood, but it has since been reduced in popularity and use (at least from my perspective).
Worked there from 2/10/98 – 9/30/98.
Working there was interesting. I had my own office, but it was a small company that had money issues. We used to sit around the lunch table and hope the mailman would bring a check from a customer so that payroll could be met. Went through layoffs – it was a choice between me and a co-worker. Part of not being laid off was the understanding that I would stop doing my technical writing duties and start doing data entry because the company generated revenue from data entry whereas technical writing was an overhead cost.

Third job: Quintrex Data Systems

There was a major life event upcoming: we were expecting our second child and financial security was a must. I sent in a resume for a classified ad in the Cedar Rapids Gazette for a QA Tester. Ad mentioned AS/400 experience a plus. Networking again! The Vice President was a neighbor from birth until about third grade, but he knows my parents and knew me. I worked there a dozen years. My first day was 10/1/1998 and I submitted my resignation on 10/15/2010. A lot of my time at Quintrex was awesome. I was the only dedicated technical writer so I .carved a niche and definitely nested. I was able to branch out into Marketing writing, User Interface design for Windows, and all sorts of other tasks like release distribution (paper copies of instructions & burning multiple CDs). My primary work was to maintain end-user and internal documentation for all their systems. There was a lot of content - multiple 500 sheet reams of paper. I requested and then was sent to conferences in Boston (2004) and Long Beach, CA (2007). I had to adapt to technology changes. The online Help was distributed in a file format called WinHelp. However, Microsoft announced that they were ending support of WinHelp with Windows Vista. This caused a conversion from MS Word to HTML.

This is an important part of my career. Why would I want to leave a good thing and go somewhere else? At the time, these were my reasons I decided to look for a new position outside of Quintrex

1. The company served the Telecommunications industry with software to landline companies.
2. CEO was 65 and refused to reveal his plans
3. There was a subtle change in company culture – documentation isn’t important.

Epilogue: After I left

1. Company was purchased by St. Louis-based NISC
2. The technical writer that was hired to replace me died from a leg clot
   
3. CEO who wouldn’t reveal his retirement plans actually retired in September.
   
4. Did on-site 3 hour training about the tools I had used to write the company’s documentation in August 2011.
   

Unnamed Hellhole in southern Iowa

---

Editor's Note: This section, Unnamed Hellhole in Southern Iowa, is the part of my prepared notes that I didn't get to talk about during the panel. On Friday, I mentioned to a co-worker that I felt somewhat odd that all the talk on the panel was about the "good" that has happened in our careers. Sometimes, there are "not good" parts of a career. Certainly, I hope the students attending the panel never, ever, have to go through what I did. The parallels between this epoch of my life and "The Empire Strikes Back" are easy to sketch as I was definitely going through a time of uncertainty. Life was certainly bleak.

---

To this point, my career had been going quite well. I had worked as a technical writer for nearly 16 years and thought I “knew” all I needed to know about this profession. Working at this place showed me I do not. Thus, I am going to tell you something that you may not hear from anyone else – there are times in life where you will realize you are in the wrong place. I consider this a misstep in my career. Swayed to leave Quintrex with false promises of building the same type of situation I had at Quintrex from the ground up and more money. Quintrex counter offered to keep me, but I didn’t even look at the number because of the above 3 reasons. Should have looked at the number. Traded security for “opportunity” that seemed like a good idea. Learned a lot about myself and my character.

• Began working there on 10/18/2010. 
• Processes in place were wrong. 
• Used a page layout app (InDesign) to maintain 100+ page user guide. ID is fine for brochures, but was the wrong tool for creating online Help in HTML. 
• Manually typed the Table of Contents, then reprinting to verify pages matched 
• Manually drew a line to margin 
• One space or two – use one unless it “looks funny” then use 2. 
• Tedious copy and paste work for other languages. 
• Stopped working there on 4/13/2011. 

Being told I was a good fit for the position has turned into a blessing in disguise. It certainly was not at the time. I had been replaced at Quintrex so I couldn't return. This was a tumultuous time in my life. I was back to searching for a job, as I had done from 2/1992 through 2/1995. I began attending daily mass at our parish. During this time, networking became key.

1. Father of a kid on my son’s baseball team came to a game with a programming language book. Started conversation about it. I hadn’t known he was a programmer. Found out he worked at where I had applied, and that since he knew my current manager, he said he would put in a good word for me.
2. Neighbor’s sister-in-law worked at my current employer, knew my current manager, and said she would put in a good word for me. She was recently reassigned to my department. My cubicle is less than 5 feet from her.
3. Fellow parish member worked at my current employer. Had known her for 20+ years. She knew my current manager, and said she would put in a good word for me.

Eventually, I interviewed with my current manager, and then followed up with HR, who told me I was the “top candidate” for the position. That thought still makes for a nice ego stroke. Job offer came via phone call during supper. When I was told what the salary was for the position, it was higher than I had imagined and took me by surprise to the extent that I didn't even try to negotiate! Always negotiate.

What kind of work do you do currently?

Software documentation

What skills are needed to perform your job?

These are ideas that are not limited to my work at my employer – spans all of career. Given: you know how to arrange words in an order that is clear and easy to read.

1. Ability to analyze and use previous knowledge to make decisions about new situations.
2. Critical thinking skills
• If you are told the system should create A, but you have never been able to create A in the system – you can only create B, what is different? What steps did the person telling you A is created take to achieve that and where are the differences between your knowledge where you only see B and the knowledge of the person telling you should be able to create A?
3. Teamwork Skills
• You have your strengths and you have your weaknesses. 
• I work on a team where my strengths (tools) and weaknesses (project management) are balanced out by others on the team.
4. Compromise
• Our department had a recent discussion about expand / collapse. This became my pet peeve issue that if you search for a keyword in the "site" search and the keyword is found and you click the search result to go to the page that the word is supposed to be on and you do a page-level search for the same word, if that word is in a collapsed section, you wouldn’t be able to find the word that your "site" search listed in the search results. We were collaboratively working on a user guide where the original design of a page had 7 expand / collapse sections and the word I was using as an example was in the seventh collapsed section. 7 user clicks to find information – making the user do more work than necessary. To go along with this, there is often more than one way to write something. Negotiating a style that you will use to make them read as if one person, one department, wrote all of the documentation.You could write:
  
• To do A, click B.
• or
• Click B to do A.
5. Philosophical differences
• There are different approaches to any situation. 
• Your experience is just as valuable as your co-worker’s experience.
6. Do not be totalitarian in your opinions and dismiss others’ opinions. 
• Who is the best writer - Shakespeare or Chaucer? 
• Often there is no right answer so you have to use the skills you gained from being an English major to analyze the situation and make a decision.

How might an English major prepare for the job market?

1. Embrace technology.
• You don’t have to own the latest / greatest gadget or use the latest / greatest Windows operating system or Mac operating system, but you should be familiar with it. I knew nothing about computers when I graduated and consider myself to be dangerous enough to think I know what I’m doing when it comes to trying to remedy laptop or computer issues.
• The trend is for companies to use social media to research you as a candidate. Your online images and words create an impression of you by people you may never meet.
2. Understand the value of a recent backup
• Consider if the device upon which you store your music collection or even your term papers for this semester were to suddenly not work. I was using my work laptop when I suddenly got an odd Windows message. The end result is that I lost a lot of data. I’ve also lost music files that were created by converting from CD to MP3.
3. Humility
• You are not the gift to writing that you think you are. You will encounter multiple people in multiple situations where what you think is “right” is exactly what they think is “wrong” and your challenge is to and Embrace that person’s opinion. Make yourself learn from that person. Adapt your world to incorporate their knowledge to improve yourself.
• Side note: In my experience, everyone thinks that they are a writer. The quip I’ve often heard is that “writing is easy. After all, it’s just typing words.” My value as a technical writer is the ability to choose the words that communicate the information the user needs and to put those words in the correct order. At every position in my career, there was always a co-worker that believed they would be able to do my job “better” than me. There is probably a person on this campus that has the same interests as you and may think they are as skilled in that interest as you are. 
4. Soft skills
• Being able to work on a team. 
• Recent Gazette article: http://thegazette.com/subject/news/soft-skills-hot-commodity-among-employers-20141019 
5. Develop good habits
• Decide that you’re going to do something at 3:30, M-F, and then track whether you follow through with doing it. 
• If you don’t follow through, analyze your motivations for not following through. 
6. Don’t be discouraged by the advertised jobs you will come across. When you go to Rockwellcollins.com or ACT.org or Corridorcareers.com, searching for "writer" or "write" will not yield many results. 
• Expand your search criteria or, perhaps, don't specify any search criteria and simply scan all available jobs. 
• There's many job titles for a "technical writer" such as "documentation specialist", "technical communicator" and so forth.

Is there anything you wish you had done while you were a student that would have prepared you more effectively for the work world?

1. Take programming classes, especially if you are interested in writing software documentation. As someone who writes about software, a basic understanding of the logic and approach to programming - what it takes to create the systems I write about – would be helpful. You can learn on your own.
2. Take a basic business class and/or accounting class. Economics, ledgers, taxes. I was in a position where I did technical writing contracts outside of regular work. Have no idea if what I did was correct or not, but I did it. <grin>
3. Spend time in the computer lab helping users solve issues with computers and software.
4. Try different things that are outside of your comfort zone. Have preferences, know what you’re good at, but don’t pigeon-hole yourself into a limited area.

 

No Filter

Here is an entire thread in a LinkedIn group I belong to that I responded to yesterday. The title of the thread is "CHMs instead of Topics for page-level help" and it's an interesting read.

kelley bennett, a Technical Writer at Suncoast Solutions, started out the thread. I've included the comments from other forum members, including mine.

---

So, just started at a new company. In looking at the current help set up, apparently the person who originally created the online help had no training in HAT use at all. So.. using RoboHelp, she set up a chm for each screen in the application. This means there are hundreds of chms... NOTHING is repurposed... and each time the current writer (besides me) has had to update anything she's had to recompile each chm... and check each one in separately! And i think there might be chm's within chms.. i'm not thoroughly sure how all this is set up, but it's rather daunting... and even, to me, frightening.

I still am a bit clueless as to what's being used to develop various applications here, but there's no way this process is efficient... and it's hideous.. also, they can't really drill down beyond the main screens to get help. Getting help from subscreen at any level requires that you back OUT of everything until you get into the main screen... in order to call the help up.

Additionally, they have rigged it in such a way that the chms are viewed over the network... previoulsy, my understanding was that each CHM would have to be downloaded and viewed locally to be used. However, I found out that they did some sort of scripting or fancy workaround that allowed them to push chms to users for use over the network/internet. At first i couldn't believe it, so I checked Peter Grainge's website and found that there IS a way to beat the system and use a chm over a network. I'm just not convinced that's a good idea.

Additionally, and obviously, this does not allow for any sort of single sourcing.

So, that said, I am writing a proposal for a change in how the help is set up an implemented. I'm thinking it won't require much change for the developers - perhaps revise the current script that is linking all the chm files - but being a very NON-TECHNICAL technical writer, i am not sure what is required for the way things are vs the way things might need to be.

In addition, I'm trying to come up with arguments for the change... the benefits of revamping the help design - which obviously will help the tech writer.

But I have to provide a good enough argument for "The Management"... so here are my questions and anything you can add will be MOST appreciated!

1) what advantages might there be in changing from this bizarre chm mess to a more traditional topic based help?
a) single sourcing is then possible
b) more fluid transitioning within the help presentation to the user
c) more efficient for the technical writer for updating and checking in?
e) someone mentioned to me that using chm over a network/internet could pose a security risk/issue/problem - can anyone verify if this is try or not and why this might be the case?
d) what advantages would updating this help process provide to developers?
e) what advantages would updating this help process provide to users?
f) seems to me (altho, I am not able to verify this at this time) that several smaller chm files would require more space and take more time to load that one larger, traditional, topic-based project would - would you believe this to be true?
g) for thick client app purposes (since recently I've only dealt with web based apps), what would be
the best output for us to propose and why?

OK.. i think that's all i can think of to ask at the moment, but as I said, if you can think of anything else to add for or against my argument to make this change in practice, feel free to list it.

I want to extend my appreciation to anyone and everyone reading and/or responding to this plea for assistance!

THANK YOU!

---

Comments

Rick Stone
Adobe Certified Captivate and RoboHelp instructor
Wow... quite a post there!

1) what advantages might there be in changing from this bizarre chm mess to a more traditional topic based help?

Maintenance is tremendously simplified and by simplifying things, it will result in obvious cost savings.

a) single sourcing is then possible
b) more fluid transitioning within the help presentation to the user

It really depends on how it was set up. For example, if it were set up as a proper merged system, folks would likely not even realize they were dealing with a highly fragmented output.

c) more efficient for the technical writer for updating and checking in?

I'll leave it to someone else to comment on usage of Source Control with this approach. Certainly there is a lot more overhead this way because of all the RoboHelp specific project files.

Inter-topic links may or may not exist today. Certainly it will be very cumbersome to create and maintain these types of links with the existing system.

e) someone mentioned to me that using chm over a network/internet could pose a security risk/issue/problem - can anyone verify if this is try or not and why this might be the case?

Only Microsoft can say for certain, but the reason CHM files no longer easily operate over a LAN is because they discovered a vulnerability.

d) what advantages would updating this help process provide to developers?

For the developers, there would be a single CHM file to deal with as opposed to hundreds.

e) what advantages would updating this help process provide to users?

Without seeing how things are set up, it's difficult to say for certain. But the way it's been described, it would seem that there is no single cohesive way for an end user to easily find information within the complete system.

f) seems to me (altho, I am not able to verify this at this time) that several smaller chm files would require more space and take more time to load that one larger, traditional, topic-based project would - would you believe this to be true?

The CHM acronym means "Compiled Help Module". The process of compiling typically results in space savings. Only by performing a careful analysis would you be able to determine if more space were needed for this method over a single consolidated CHM (or other) methods. But I'd say that generally speaking, that would seem to be the case.

g) for thick client app purposes (since recently I've only dealt with web based apps), what would be the best output for us to propose and why?

Typically folks opt for CHM usage when they have a locally installed software application.

Sounds like you have an interesting journey ahead of you!

Cheers... Rick :)

---

Carlos Mills
Senior Technical Writer at AWTA Ltd. (Aus)
I have being working with RoboHelp for quite some time and I would recommend to import all Chms into one single project using RH import feature. If you do not have the CHM source files (Word or HTML) you may decompile the CHM files as single projects and then import each of those projects files into your master project.
Even though that involves a lot of work it will save enormously in the long term maintenance and enhancement of the system.

---

kelley bennett
Technical Writer at Suncoast Solutions
Thanks guys for your input... And yep, Rick, it's quite the mess... Thanks Carlos, for the past 10 years I have not needed to do any importing using RH or Flare so I had completely forgotten that as an option to pull all of the info into one without the old copy and paste tedium... THANKS!

---

kelley bennett
Technical Writer at Suncoast Solutions
Hi Rick,

Quick question... since I have never used chm for page-level help, I am not sure how that would work. I always thought I would need to use a non-chm form of HTML output... can you provide additional info on using chm for page-level help?

thanks!

---

Rick Stone
Adobe Certified Captivate and RoboHelp instructor

I've seen it work in a couple of different ways. In way number one, all your "page level" topics are in one single CHM file and all the other typical topics of the system are in a separate CHM file. So in this case you have two CHM files to maintain. One for the CSH page level topics and the other for all the other topics.

The other way is to simply have all topics inside the same single CHM. Then when you need a page level topic for CSH, you call only that topic.

To do this, you use what is called a "Map File". Basically a map file is a text based cross reference. Each potential exit point from the application that would normally open a page level help has a unique identifier. As the help author, you will need to use RoboHelp to establish the correct mapping to topics for each of these identifiers. To get to this area, you open the Project Set-up pod in RoboHelp. In that pod, you should see an area for Context Sensitive Help.

For more details on this process, check out the link below:
http://www.wvanweelden.eu/articles/context-sensitivity-webhelp-and-flashhelp

Note that Willam's article is specific to WebHelp and FlashHelp. But the general principles are the same for CHM.

And here's a Microsoft article on it for CHM (not quite as easy to follow as Willam's article is)

https://support2.microsoft.com/kb/189453

Cheers... Rick :)

Earl Eddings

Advisor: Technical Writer at CSC (GIS)

@Kelley Bennett's original post -- Wow, just wow. That is amazing. *shakes head in disbelief*

Rick Stone

Adobe Certified Captivate and RoboHelp instructor

@Earl - That was my first impression!

Made me recall an old issue from my days working in a call center. I was in a specialized area that supported things that the company I worked for didn't offer. For example, how to install Microsoft Office or how to use Microsoft Paint. Folks paid $2.25 per minute to get advice from me and a co-worker.

Someone called with a problem using the old "Microsoft Cardfile" application. In a similar way to what Kelley was reporting, instead of creating a new card for each contact, they created a complete new Cardfile file for each contact! When it came to light that it was much easier and more efficient to use it as intended, the person DEMANDED that we send Bill Gates to his doorstep so he could fume at him personally.

Ahhh, the good ole days!

• Earl Eddings

  Advisor: Technical Writer at CSC (GIS)

  @Rick That's hilarious!
• Paul Hanson

  Software Technical Writer

  By your own words, you are a "very NON-TECHNICAL technical writer" so before redesigning or doing any rework, you need to have an understanding as to why things were done the way they were. If it was truly done the way it was done because the previous writer didn't know what they were doing, then that's one thing. After you understand why the writer did what they did, then you can look at a better way.
  
  A long long time ago, I had a master.cnt file that linked together (roughly) 100 WinHelp files. I had a good reason for doing this - there were 13 collections of screens that went together so there was a 1:1 - and (roughly) 87 .exe files. Anyone that didn't understand the reasoning behind creating 100 WinHelp files would call it a mess.
  
  My point is that there was a reason for doing things the way I did and you don't know the reason the previous writer did things the way they did. Only after you know why can you be qualified to say, "the current setup is stupid and a mess" or "the current setup is not stupid and makes sense." In your shoes, I would dig through any "old" documents or source files for this help system to see if there was any sort of explanation for why it was set up the way it was. Pick the brain of your co-workers that worked with the previous writer and, if it still doesn't make sense, find that writer's email address and ask, "Why did you set up the help files the way you did?" You may be surprised with the response!
  
  Good luck.
• Rick Stone

  Adobe Certified Captivate and RoboHelp instructor

  @Paul - It certainly depends on the situation as well as the content of the files. When I was cutting my teeth on help using Winhelp and RoboHelp version 2, I ended up with a system that linked 250 or so separate WinHelp files.
  
  Note that each of these had far more information inside them than a single topic. ;)

Paradigm

I worked at a software company for a dozen years that I've described on this blog. One of the five that started the company, LJS, held a class about paradigms. It was many years ago but if I recall correctly, he divided all of the employees into groups and then, for two days in a row, we met in the empty side of the building. Each time we met, the first agenda item was to watch a video about paradigms. What I remember about the video was the example of the Swiss watch maker company. For whatever reason, that company didn't adapt to the changes around them and, eventually, the company went out of business. After watching the video, we had a discussion about what could be changed to make our life better at work. We talked about this statement: "What is impossible today, but if it could be done, it would change the way in which we do our work." Unfortunately, that may be a cheap paraphrasing of what we talked about since it has been several years since I saw the phrase on a PowerPoint slide at a monthly staff meeting or heard LJS say it.

Side note: I also remember that on the second day, a co-worker openly challenged LJS and asked why we had to watch the video. In her defense, she felt the discussion we had were addressing some workplace issues. She asked, "Do we have to watch the video?" Apparently, LJS felt disrespected and ordered her to leave the room. By the end of the day, she had been terminated.

Back to the point. In my career, I've gone through several paradigm shifts. In bullet list form, here are some of the ones that stick out in my mind, though I will tell you that digging through this blog would reveal quite a few more. Here's the bullet list with some highlights of what paradigm shifts I made at that employer over those 12 years:

• I began creating online Help with RoboHelp in a format called WinHelp. In the early days, I considered a "great" and "useful" online Help system to mean that to access field-level information, you clicked a "Help" icon, which accessed a secondary window, which had a list of fields. To get field-level information, you had to click each field individually. 
• The next shift was when the makers of RoboHelp released a DLL for WinHelp called "WinHelp 2000". The selling point of WinHelp 2000 was that it gave you a TOC pane on the left and your content displayed in a pane on the right. The downside of WinHelp 2000 was that secondary windows were not supported. To use WinHelp 2000, I had to remove all of the lists of fields and change to numbered procedures. 
• The next shift was when Microsoft announced that they were discontinuing support for WinHelp. For years, there had been a movement to convert from WinHelp to HTML but I staunchly stood firm as a WinHelp supporter. I refused to convert because there was no business case to do so. Microsoft's announcement gave me the business case to convert. When I began converting my 100 WinHelp files to HTML, I used tables to control my layout. 
• The next shift was when I learned that web pages that used tables to control layout were not highly regarded. Others in the technical writing community were creating HTML-based online help that only used tables for tabular content. 
• The next shift was hearing about something called CSS. Span tags changed my world because I could create a span tag and use it to globally change the appearance of specific text. I began replacing the single span class called "programname" to make text bold with multiple span classes, one each for each UI element. I created span classes named "check_box", "menu_option", "button", and "drop-down." 
• The next shift was hearing about something called JavaScript. I saw a web page that used  JavaScript to create a mini-TOC for the web page. I stopped manually coding a list of headings on each page. 
• Somewhere in the mix of all of this, I heard about DOS batch files. I had been manually copying files from one directory to another but with an amazing command called "XCOPY", I could do all of that manual work automatically (automagically?) by creating a DOS batch file that compiled my RoboHelp projects and copied PDFs from one directory to another prior to publishing. 
• The next shift that was happening over all of this time was to take ownership of the content. I exhumed "Hit the Enter button" in the documentation. I got rid of all the ugly language and poor writing.

I am now undergoing yet another paradigm shift at work and I accept the challenge. I've been a technical writer since 2/10/1995 and feel the beginnings of a paradigm shift in what I do at work, which is write software documentation. For example, why do I need to write that to add a class, you select a button that has a label "Add Class"? Why do I need to write that to enable pay notification, you select a check box that has a label "Enable Pay Notification." Why not tell the user that when you 'enable pay notification' this or that or the other thing happens in the system and what outcome is achieved by selecting that check box?

A lot of this is shifting in my mind on a daily basis. I don't know what it's going to all look like, but I'm excited.

Ah, the Good Ol' Days of OV to WinHelp

From: me

Good point Paula – and I totally agree that retyping may be easier in some cases. I wasn’t trying to make a blanket statement that my guestimate of 1 hour would apply to Carrie’s content.

In fact, now that you mention it and I reread my post, there was no way you could have known that I was remembering 10+ years ago when I worked for a different employer. One of my projects was to convert hundreds of OfficeVision (an AS/400 word processor) documents to Word / WinHelp. That was when I ended up with a master.cnt file and 100 .hlp files, when it was all said and done. I don’t know if you remember that, but a lot – and I mean A LOT – of people on HATT helped me through that conversion, like Char, Rick Stone, Paul O’Rear, Bill Swallow, and you. <grin> Please, don’t be insulted if I didn’t specify you in that impromptu list!

During that conversion, there was a wide range of page lengths. Some of the existing documents were really short – a page – but those counterbalanced the ones that were 50+ pages. I’m remembering a specific existing 65 page doc that was part of that conversion. It had not only content about the menu options that were on the screen, but bundled with it, there were implementation procedures of let’s say 6 steps each. The system I was working with was for a billing system used by telecommunication companies and this specific one had 15 menu options. One of the things I was also dealing with was cleaning up garbage like:

“To run the <State_Name_Calling_Plan> menu option, the user must have authority granted by your system administrator or another authorized user, if you don’t have a system administrator. Running the <State_Name_Calling_Plan> menu option requires that the user has an authority record set up through the Authority Maintenance menu option, which is conveniently located on the System Controls menu. If the user does not have access to the System Controls menu, the user cannot access the Authority Maintenance menu option to set up authority for this menu option – it must be granted by your system administrator or another authorized user, if you don’t have a system administrator. The <State_Name_Calling_Plan> menu option cannot be run during the Billing Cycle. Consult the documentation provided about the Billing Cycle to determine when the <State_Name_Calling_Plan> menu option should be run and what menu options must be run before the user can run the <State_Name_Calling_Plan> menu option. ”

Can you hear that blurb screaming, “Rewrite me! Please! Save me from this dribble! Create snippets about the <State_Name_Calling_Plan> menu option, about Authority Maintenance, about the System Controls menu, and about the Billing Cycle! Please! I’m begging!” I wish I had that source file available to look at, but it’s on a CD-R at my former employer. Cleaning up junk like that is why I wrote, “you guestimate that on average, it will take you 1 hour to convert each “chunk” to your new tool. You came up with that number because you have several long topics that will counterbalance several small topics that will take minutes to convert.”

Anyways, that’s where my head was at when I responded to Carrie’s post.

Happy New Year! We are planning to watch “Grown Ups 2” with our 17 year-old daughter, her friend that is a boy, and our 15 year-old son. BTW, if anyone saw GU2 and thought it was awful – it’s on a bunch of “Worst Films of 2013” lists – feel free to save me! At 44, it’s safe to say my “out all New Year’s Eve” times are over.
<snip>

From: Paula R. Stern

<snip>
The first question is why it would take an hour to convert a chunk of information? If that were true, you could type that chunk faster into a new tool than that estimate. If you really think it would take that long to go from any tool to any tool, that's what I would suggest you do – just go type it over again, given that a chunk really shouldn't be longer than a page (and often less).

Without commenting on what tool goes to what tool – most content can be imported in far less time than one hour per topic/chunk. Honestly, if it would take that long, you could probably export it to PDF (takes minutes); export that to Word – with the latest Acrobat version, what you get isn't that bad - and then import it into RoboHelp, Flare, whatever.

We are in the process of moving one client to RoboHelp – they are using Doxygen at one daughter-company; LaTeX at another. As part of the rebranding, we just took PDFs from each of these outputs, exported that to Word and reformatted it properly according to the new template. A 100 page document (probably around 200 chunks of information/topics), took us less than 5 hours to import and reformat. Importing it to RoboHelp shouldn't take more than 5 hours once it has been properly formatted – if that.

So, I estimate 10 hours – let's double it for argument's sake and to make the math easier. So – 10 hours to import 200 topics comes to 20 topics an hour, or 3 minutes per topic.

Using your equation of 1,000 topics – we're talking 50 hours – or $2,500 – even doubling that – you still come to $5,000. The learning curve for some applications is longer than that. Again, this is a real life, just done example of moving from PDF to a help authoring tool – in this case RoboHelp, though I have no doubt Flare would be just as fast.

I agree that going into AuthorIT would take much longer and be more complicated but if the direction is AuthorIT to RoboHelp (or Flare), honestly, piece of cake.
<snip>

From: Rhonda Bracey

Spot on Paul. And don’t forget the cost of training, and perhaps getting in a consultant to help set up new templates etc. for the new tool. Back in 2009 I wrote a blog post on just this – I still think it’s as relevant today as it was then: http://cybertext.wordpress.com/2009/02/16/the-real-cost-of-new-software/
<snip>

From: Me

<snip>
I realize I am chiming in a bit late, but I wanted to point out the ‘hidden cost’ to converting from one tool to another - the total number of hours you will spend just to get from your current tool to your new tool.

I am using the numbers in this example because I suck at math and I’m knee deep in work so bear with me.

Let’s say your hourly rate, whether you are salary or not, is $50 / hour. That’s the number your employer uses for calculating its salary budget. Further, let’s say in your existing documentation, you have 1000 topics or chunks of text that need to be converted from AIT to RH, Flare, whatever. Further, after analyzing your content, you guestimate that on average, it will take you 1 hour to convert each “chunk” to your new tool. You came up with that number because you have several long topics that will counterbalance several small topics that will take minutes to convert.

So, with your 1000 hours of work, multiply that by your hourly rate ($50) and you get a conversion “cost” of $50,000 and after your employer spends $50,000, they will *just* have your existing content transferred from one tool to another. There won’t be any “normal” updates of your content. The newest feature that all your customers are begging for? It won’t be included. The new topics you are planning to write based upon your Support department’s Top 10 Questions We’re Asked on a Daily Basis – those won’t be done. You will simply have the exact same content you have now but instead of opening AIT, you will open RH, Flare, or whatever.

And, if you fire up your calculator and divide 1000 hours by 40 hours, you’re looking at 25 – 40 hour work weeks that will be spent converting and, really, how many of us spend 40 hours only on a single task? It’s never been realistic in my nearly 18 years of being a technical writer.

Good luck with your situation - I hope it works out well for you. Please keep the list informed of what you end up doing!
<snip>

From: Carrie Zinck

Thank you all for your advice regarding the switch. I’m very interested to see how many of you suggested Flare as a better solution. As I finish this comparison matrix, I’m going to add Flare to the list and see if that might be a better compromise.

I so appreciate you all!