Monday, July 10, 2017

Just Answering the Question

Received a request to complete a survey about language and technical writing. I like telling the story of my career so when I read this question:


I wrote the following:

At my first gig, in 1995, my mentor liked the phrase "for which" - we wrote user manuals that had a definition / description for each field in the system. Thinking back to that type of writing, we didn't have any procedures in those user manuals. It was all individualized field-level definitions. When I was at my 3rd TWing gig from 1998-2010, I attended two WritersUA conferences - 2004 (Boston); 2007 (Long Beach, CA) - and heard many great speakers. It was during this time that the company wanted to convert from the same type of field-based content to WinHelp, using RoboHelp. It was the perfect storm to transform my writing:
  • attending those conferences
  • reading multiple TWing-related lists (the Techwr-L list, HATT),
  • participating on the RoboHelp forum
  • being introduced to HTML, CSS, and JavaScript
  • Ultimately, I created a modular WinHelp system of 100 WinHelp files. All the content was transformed from numbered field-level descriptions to tasks, even if the task was to "Add a Widget", "Change a Widget", and "Delete a Widget." I was very proud of that work.
In a job change that has been the biggest mistake I have made thus far in my career, I went to a medical devices company that wanted to 'get into' software development. The Senior TWer in the dept was dumb. She used InDesign for a 150ish page manual, but 1) didn't use styles - she manually typed the TOC, including the ... to the page number, then the page number. Her release process was to print the 150ish page manual and manually verify the TOC was correct. If it wasn't, she would fix the TOC and then reprint - she bragged about staying until after midnight to get the manual done on time - I suggested using styles, she dismissed it as "too complicated"... 2) when I asked if the company standard was one or two spaces after a period, her answer was "use 1 unless it looks funny, then use 2." 3) insisted on making the manual match the software, including the ... on a menu option like File > New... - which okay, fine, but the style was to write "From the File menu, click New...." The "File" and the "New..." were styled as bold so the manual had 3 bold periods, followed by a single unbolded period - it looked hideous. They also wanted me to figure out how to author in InDesign and generate a CHM file and a PDF. Short answer: you can't. You can generate a PDF from ID, convert it to Word, import that into a HAT, like RoboHelp, and generate a CHM, but because of all the manual formatting in the ID files, going the PDF to Word route was hideous. On top of that, it would ultimately amount to having two source docs - one in ID, one in HTML.

Thankfully, I got out of there (though going on a job search was not what I wanted to do at the time) and moved on. At this job, I attended another WritersUA conference (2012) and bought into snippets / user-defined variables to store text or graphics that were used in more than one topic. We used Confluence. The language was quite stuffy and pretentious instead of being simple.

After being laid off from that company in January 2016, I now work for a university IT dept. My primary project is a disaster recovery manual. I am using RoboHelp to assemble it. The server teams have Word docs and other files in a shared network directory and I link to those files. There are 16 critical systems. After 1 year, 3 months, 1 week, 5 days, I am making the right connections. The editing I do on these linked documents is to standardize phrasing, such as changing "Run this command to do XYZ" to "To do xyz, run this command" - things like that.

Working as a technical writer has been a rewarding career.

No comments: