Search This Blog

Showing posts with label InDesign. Show all posts
Showing posts with label InDesign. Show all posts

Monday, June 13, 2022

Terrible Advice that is True

I was reminded of both working at Quintrex as well as working with the Senior Technical Writer at the Unnamed Hellhole in southern Iowa when I read Page Ranges in a TOC this morning, which says the following:


Colin asked if it is possible to construct a table of contents so it includes not just a starting page number, but a range of page numbers. For instance, the table of contents would include 1-1 to 1-22 instead of just 1-1.

Unfortunately, this is not possible in Word. The table of contents feature is designed to only include starting page numbers. It would appear that this decision is related to the fact that determining a starting page number is easy (it is the page on which the related heading starts), but an ending page number for a section is not as easily determined. Where a section ends depends on what headings you instruct Word to include in the TOC.

If you want page ranges in your TOC, the only way to get them is to manually enter the TOC and not rely on Word to create one automatically.


When I worked at Quintrex, BSS was my co-worker. He used to write documentation in Microsoft Word. 

One day, he showed me that how he created a table of contents for one of his documents. 

For each section that he wanted to have included in the table of contents, he selected the text and clicked Insert > Bookmark. He repeated this process for each heading throughout his document. 

Then, on the table of contents page, he typed the name of each bookmark - he did not use any Word styles in his document - typed the leader dots [.....], then the page number. After typing the page number, he selected the page number and clicked Insert > Hyperlink and selected a heading in his document. He repeated this process for each heading in his document.

Thankfully, when he showed me his process, I was able to show him how to insert a TOC field which automatically builds the table of contents. 

I chuckle about it now. When I left Quintrex to go to the Unnamed Hellhole in southern Iowa, the tool that was being used for one of the user guides was InDesign. In context, InDesign is typically used by a marketing department to create short (generally, under 10 pages) documents. However, at the Unnamed Hellhole in southern Iowa, InDesign was being used for a (roughly) 150 page user guide. The Senior Technical Writer at the Unnamed Hellhole in southern Iowa followed a similar process of manually creating the table of contents for that 150 page user guide. In fact, the Senior Technical Writer at the Unnamed Hellhole in southern Iowa went a step further and printed the entire 150 page user guide to manually verify that the page number in the table of contents matched the actual page in the body of the document. The Senior Technical Writer at the Unnamed Hellhole in southern Iowa went further to brag about staying at work until midnight on the night before the new version of the 150 page user guide was due, providing details of printing the 150 page user guide multiple times which, to me, proved that the process followed by Senior Technical Writer at the Unnamed Hellhole in southern Iowa was ... stupid. It was an absolutely terrible process and to brag about being required to be working on the 150 page user guide until midnight beautifully illustrates how the process was a broken process and the utter and complete incompetence of that Senior Technical Writer at the Unnamed Hellhole in southern Iowa. 

It is good advice to tell someone (Colin) that the intended goal is dumb. If you really want to know when a section ends, look at the table of contents. For example, look at this table of contents:

Section 1............... 1

Section 2............... 15  

You can see that Section 1 starts on page 1 and Section 2 begins on page 15. That tells someone looking at the table of contents that Section 1 is 14 pages (pages 1 through 14). As a side note, I'd add that I've never seen a table of contents that shows a page range for a section. It is always good advice to tell someone (Colin) that the intended goal of what you want to do is unattainable. As it is written, the author of Page Ranges in a TOC made me think of two former co-workers who manually created a table of contents, which is wrong.

Thursday, May 31, 2018

Frustrating!

Something odd happened - my Adobe software is gone! I use Dreamweaver every day!! I submitted a ticket to the Help Desk so hopefully this is just temporary.

Here's how Adobe is integrated into my life at work.

This is on my Start menu - I created this group because they are apps that I wasn't using every day so I didn't want it to clutter the menu.


This is on my Start menu - Adobe created this group when it was installed. I used these programs more frequently.


This is what I see for the "Adobe Creative Cloud" - it says I can 'try' or 'buy' but I already had them.

Wednesday, April 4, 2018

Want to Irk Me? Use MS Word like THIS

I'm permanently scarred from working at the Unnamed Hellhole in southern Iowa - that's the only conclusion I can arrive at when I feel the disgust flowing through my bloodstream as I view a MS Word document that is formatted like the following:


The Unnamed Hellhole in southern Iowa gets all the credit / blame because that is where the other writer in the department with the title "Senior Technical Writer" insisted upon using InDesign entirely the wrong way. There is no justification to manually type the TOC entries, the leader dots, and the page number. There is no justification to print the 100+ pages in the document to manually check that the page number in the TOC matches the body of the document. There is no justification to state that the "rule" for using one or two spaces after a period is to "use one unless it looks funny, then use two."

I have no doubt in my mind that the aforementioned ex-co-worker would have seen nothing wrong with the screen capture above.

Thursday, March 29, 2018

In My Pursuit of a Backup Solution

Was reviewing this product - https://www.paragon-software.com/medium-large-business/protect-restore/features.html - and looked at this PDF: http://download.paragon-software.com/doc/PPR-ENG/Protect-and-Restore-full-features.pdf. I noticed it was created in InDesign. It made me wonder if the Unnamed Hellhole in southern Iowa pulled their head out of their bum and started using InDesign like a real technical writing tool. Of course, if I was still there, I'm fairly certain I would have ditched InDesign in favor of RoboHelp to write their user guides for their software. Even the documentation that had to be translated into multiple languages likely would have found a home in RoboHelp.

Did I mention I really like RoboHelp?

Speaking of RoboHelp, I had a great meeting yesterday with a steering committee (with Senior Directors in attendance, including my manager's boss) about Knowledge Management. I spoke about snippets during the meeting and rattled off statistics about 8 sample documents I have been working with which had 121 paragraphs & 62 graphics. Of the paragraphs, 58% of the content existed in multiple documents. Of the graphics, 55% of the screenshots existed in multiple documents. What I need to do, for the next meeting, is to create a proof of concept that I can show to the attendees. I think talking in generalities is not nearly as powerful as showing a demo of how I would use snippets in our Knowledge Articles that will be our Knowledge Repository. I wrote about snippets and Cherwell's lack of support for snippets on the Single Sourcing Rant page, if you want to read more. I walked out of yesterday's meeting pleased with myself, for explaining why snippets are awesome, as well as hopeful about the way I want to create Knowledge Articles for our department could be adopted.

Wednesday, November 1, 2017

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:


Thursday, September 28, 2017

Nope Nope Nope NOPE!

All the experience and all the tools that are listed below and you're only valuing the work at $19 an hour as a low range and $20 as a high range? What happens - do you start at $19.50 / hour and then get rewarded for being a 'rockstar candidate' by getting a 50 cent raise up to $20 / hour?!? What a BOGUS (!!!!!!) situation!!

HTML eMarketing Associate
Aureon Staffing - Des Moines, IA
$19 - $20 an hour - Full-time, Contract
Are you someone who excels at coordinating and executing mail marketing initiatives? If so, we have the perfect opportunity for you!
Job Summary: This is a 3-6 month contract for full-time work. Hours are Monday-Friday 8a-5p. Pay rate is $19-$20/hour, based on experience. Position could become permanent for a rockstar candidate. Primary positional responsibilities include:

  1. Create eMarketing Campaigns for clients
    1. Oversee implementation and customer support for email products, coordinating with writers and designers to produce finished products.
    2. Maintain records and work flow according to standard operating procedures.
    3. Troubleshoot technical issues related to HTML templates, list segmentation and other aspects of email execution, as required.
  2. Email Deliverability
    1. Prep email lists and schedule email sends for a variety of mailings: quarterly, A/B testing, surveys, and campaigns.
    2. Utilize deliverability tools (ReturnPath) to research deliverability issues. Accountability and ownership of email delivery.
    3. Follow all established SOPs; works within all established guidelines and deadlines.
  3.  Marketing Cloud Support
    1. Takes initiative on learning about the capabilities offered in the Marketing Cloud suite and how they may be applied to the company.
    2. Able to write queries to pull email data and reports.
    3. Collaborate with Salesforce Marketing Cloud (ExactTarget) to resolve issues on system functionality, list management, tracking of email sends and other miscellaneous items.
Qualifications:
Thorough understanding of email marketing concepts and the execution of electronic marketing campaigns
  1. STRONG BACKGROUND IN HTML AND ABILITY TO CODE EMAIL FROM SCRATCH
  2. Proficient on PC/Macintosh: Microsoft Office (emphasis in Excel), Dreamweaver or related program, HTML design specifically for email preferred, Adobe Photoshop, Adobe Fireworks, CSS
  3. CSS and JavaScript helpful
  4. Familiarity with relational database structures
  5. Salesforce Marketing Cloud experience or similarly applicable background; knowledge of AMPScript
  6. Familiarity with InDesign
  7. Strong oral and written communication skills
  8. Nonprofit industry awareness helpful
  9. Strong visual skills and comfort with basic design principles
  10. Must work effectively with all internal staff, be a team player, professional, be able to take constructive criticism and direction
Company Overview:
  1. Here at Aureon, we believe in integrity, compassion, values, teamwork, accountability and a great customer experience for both our clients and candidates alike. Our direct hire placement division prides itself on finding you just the right opportunity where you will learn, prosper, and grow in your career. We want to talk to you confidentially about your goals, aspirations and what you are looking for in your next opportunity. We place the top twenty percent of talent with top organizations.
  2. Partner with us, and let us help you to put your best foot forward.

I hope no one I know would accept working for a customer that believes "deliverability" is a real word... these work conditions would suck...

Friday, June 9, 2017

I'll Stay Where I Am

In my Indeed job email, there was an opening in Mount Pleasant, IA. I know that when I worked at that Hellhole That is Not Named, I had a co-worker who lived in Mount Pleasant. I also remember Alex played a basketball game there and then left his jersey in the locker room which meant Karen and I drove to Mount Pleasant on a day off of work to retrieve it. Anyways, I was curious how long of a commute it is and this is what mapquest.com said:


Why would anyone take "route 2" which adds 33 minutes to the drive?!?

No, I'm not going anywhere. In fact, I feel really REALLY good about work. The Disaster Recovery documentation is shaping up - perhaps I will post an overview in the future of what it's shaping up to look like, as far as structure.

Here's the job description. It requires the use of InDesign, which I hate* and PageMaker**. I have no interest in leaving where I am. 

Technical Writer - Mount Pleasant, Iowa

Hearth & Home Technologies - Mount Pleasant, IA

Help us prepare and manage all installation documents necessary for our family of products as a Technical Writer in Mount Pleasant, Iowa at Hearth & Home Technologies. This rewarding career includes competitive compensation, comprehensive benefits and a supportive environment focused on developing your skills.

Our Technical Writer is responsible for the technical writing, editing and content management of product installation manuals, warning labels and user guides intended for customer use for Hearth & Home Technologies’ products. You’ll be working with the production, engineering, new product development, technical support and marketing departments to accurately capture HHT products in a written and pictorial/graphic format.

Hearth & Home Technologies believes in the power of a Lean Manufacturing, Quality and Safety focus. Our Technical Writer plays a vital role in ensuring compliance with all labeling requirements and clearly communicating installation and user information to make sure all parts are properly installed and utilized to support objectives at Hearth & Home Technologies.

Your role as a Technical Writer

  • Perform technical writing, editing and content management of product installation manuals, warning labels and user guides. Interacts effectively with engineers, designers and product managers to understand critical product features requiring explanation in product documentation.
  • Coordinate document changes and ensures consistency between documents through interaction with offsite documentation staff. This includes ensuring basic standards are met for document quality, clarity and content at other HHT locations.
  • Ensure appropriate safety and warning content is properly presented in the product documentation and labeling through interaction with engineering, purchasing, quality, reliability, product liability, agency, governmental bodies and other resources.
  • Maintain familiarity with applicable standards and codes to ensure compliance of product documentation and labeling consistent with the required standard of care.
  • Ensure product documentation is properly controlled and that current revisions are available for both production and approved user access on a timely basis.
  • Perform special projects related to continuous improvement of documentation and documentation systems. Supports strategies for the implementation of document improvement and change.

Requirements

The requirements of a Technical Writer
  • 4 year degree and 3 years’ experience in technical writing or a combination of education and experience.
  • 3 or more years’ experience working with desktop publishing software, including but not limited to, PageMaker, InDesign, Illustrator, PostScript (Auto Cad), Acrobat Professional, and Photoshop.
  • Ability to interact effectively with technical staff. Able to grasp technical and safety implications and transform them into effective instructions.
  • Must be a team player, results oriented and able to work in a fast-paced and changing environment.

About Working for Hearth & Home Technologies

Hearth & Home Technologies is the world’s largest developer, manufacturer and supplier of fireplaces, stoves and hearth products. As the Hearth Experts™, we thrive on continual innovation and work to incorporate the latest in material, design and technology. Our consumer-focused approach, strong brands and streamlined value chain help us lead every aspect of the hearth industry.

Lakeville, Minnesota is our home, but we have locations throughout the United States. Hearth & Home Technologies is a subsidiary of HNI Corporation (NYSE: HNI) and serves residential and commercial markets. HHT produces the industry’s best and most-recognized brands, including: Heat & Glo®, Heatilator®, Quadra-Fire®, Harman®, SimpliFire™, EcoChoice™ and PelPro™. The company also manages Fireside Hearth & Home™ retail stores and builder design centers.

Why Choose Hearth & Home Technologies

  • Working for the industry leader of a product that people love
  • Competitive compensation and benefits
  • Positive environment where we work together as a team
Take the next step in your career by applying for a job today.



* Editor's Note: Hatred of InDesign is tied directly to the inability of co-workers to use it correctly, which is to not use it to maintain a software user guide with a manually typed TOC and not styles and no standard for using one or two spaces after a period (the rule was "use one unless it looks funny, then use two") and manually drawing a line from the end of a heading to the right margin and ... and ... and ... yeah, all of those are closely related to how InDesign was being used, not the actual product.

** Editor's Note: PageMaker was used in college (25 years ago) to lay out the Reflections literary magazine. It wasn't a favorite tool then. PageMaker ceased active development in 2004. Read more here.

Monday, February 20, 2017

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

Thursday, February 4, 2016

You're Awesome - Tell Me More - OOD Part 3

Related Posts:
How to Live in an OOD Dream - Part Two
You're Awesome - Tell Me More - OOD Part 3
OOD (Object-Oriented Documentation

It's not about the tool.

While I have my favorite tools for documentation, I realize that, by extension, every technical writer has a favorite tool. The point of these OOD posts has not been to declare some slick slogan at the end like Confluence Rules, All Other Tools Drools. If any of these posts has swayed you to believe that you can't obtain the OOD dream if you use this tool or that tool, you've missed the point. The bottom line concept of OOD is to treat each segment of information as just that - a segment. Segments can be arranged and structured and maneuvered any way necessary. Further, by separating content from presentation, the appearance can be quickly changed to adapt to new requirements.

Here are some links to expand your mind.
  1. Separate Your Content from Presentation
  2. Using Confluence
  3. Using Microsoft Word

More of the OOD Dream - Part Two

Related Posts:
How to Live in an OOD Dream - Part Two
You're Awesome - Tell Me More - OOD Part 3
OOD (Object-Oriented Documentation

It was a nightmare to track.


It was a nightmare to update.

Documentation was maintained as Word files. We had one area of the system that had a 5-7 page section written about it. Those 5-7 pages were in - let's say - 10 different User Guides. When there was a change to that section, the change was written, and then I, or someone in the department, had to open each of those 10 different User Guides and manually copy the rewritten text and paste it into each Use Guide. Yes, that was done 10 times - once for each User Guide.

It wasn't just at my most recent employer. For a dozen years, I worked in an environment where the amount of copy and paste would stagger anyone. And it wasn't just text - screenshots weren't even maintained as separate chunks of information. A screenshot was taken and then pasted into a document. If that screenshot changed, I had to remember all the different places it had been pasted. I was able to do this work only because I created all of the documents and, like a database, I expanded the connections between documents in my brain. I also used a tracking document - also a standalone collection of information - to help me remember what changes had been made.

But there's another aspect of OOD that I haven't even mentioned. It's the aspect of separating "Content" from "Presentation". Andrew Plato, a former member of the Techwr-L list, used to go on rants about how the most important aspect of technical writing was the content, not how pretty the text looked. I think following the principle that content is tagged so that its appearance can be changed by a single change to a file - whether it is a CSS file or a Microsoft Word template - is tremendously helpful. It's too easy to get bogged down in whether UI elements should be bold or italic or in a different font or size. If the content is tagged as, say, a "check box" and all content about a "check box" have that tag, you can define what formatting should be applied to that "check box" tag. I like to use the example that you are writing a document and decide that all references to a check box should have bold and italic applied to it. Then your boss comes by and states that customers are having a difficult time with the way the document is formatted and requests that all references to a "check box" should not have bold and italic, just bold.

When your content is separate from your presentation, this is an easy request. You edit the file that stores the formatting information and all references to a "check box" are instantly updated per your manager's request. When your content is not separate from your presentation, this can potentially be a very long and complex request to complete. You may have to search through many documents to manually find the references and apply the change.

How to Live in an OOD Dream - Part One

Related Posts:
How to Live in an OOD Dream - Part Two
You're Awesome - Tell Me More - OOD Part 3
OOD (Object-Oriented Documentation

Introducing OOD


It is the next new buzzword in documentation and content creation: OOD.

I created this term after I came across this definition of Object-Oriented:
|
An approach to structuring software applications. Instead of thinking of an application as a process with steps, we think of it as a set of objects that exchange messages. Now the dominant approach to software development. Java and Visual Basic are object-oriented software development languages.

Source: http://www.appian.com/bpmbasics/bpm-glossary/?letter=o
|
As a professional communicator, I embrace this definition. I usually see "Object-Oriented" followed by a noun, such as "Object-Oriented Programming." Thus, tweaking the above definition and incorporating the noun it describes, I offer the following slightly tweaked definition as the guiding principle of my work in the technical writing profession:
|
An approach to structuring technical documentation. Instead of thinking of technical documentation as a collection of procedures with steps, we think of it as a set of objects that communicate information.

|
Theories are like standards - there's so many different ones, all you have to do is pick one. The question always comes down to how does the pie-in-the-sky theory relate to daily - and I'll say it - grunt work when your duties are to write documentation.This post begins to build the bridge between the theory of OOD and the translation of the theory into practical terms.

First of all, this is not a new thing for me. For roughly the last 4 years, I have subscribed to the theory that writing documentation - whether it is for a Disaster Recovery manual or software online Help - is not done the ODD way when the content is thought of as a "document" that is a silo of content, especially if that content is also in other documents.

In my mind, "documents" have a subliminal context that it is a stand-alone container of information. Traditionally, a document can be a Microsoft Word file, a Dreamweaver HTML file, an InDesign file, or any other file that writers use to store the information that is ultimately distributed to the audience. I'm adding the subliminal context that content in a document is not shared between another document. For example, let's consider a real-world environment. For the same system, there's a Quick Start Guide and a User Guide. The Quick Start Guide is a brief - probably no longer than 3 pages, preferably 2 pages - of what a user has to do in order to set up the system. The User Guide is a collection of all the tasks a user can complete. Because the Quick Start Guide and the User Guide are about the same system, there is overlap in the content because both documents include two types of information:
  1. concept
  2. task
In the "documents" paradigm, these two guides are considered separate entities. They are maintained separately. If there is information that is identical between the two, it is written in either of the guides and then pasted into the other. Because the Quick Start Guide is shorter, sometimes it is necessary to remove content to adhere to the page length. What this does, then, is create two versions of the same content.

That is bad.

In an OOD environment, there is a single source of the content. That content is then tagged for the intended output. For example, a conceptual paragraph is only going to be in the User Guide so it would have a "User Guide" tag applied to it.

By the way, Help Authoring Tools (HATs) have done this for years. Flare and my personal favorite because I earned a MVP Certificate for it - RoboHelp - have this functionality. What I'm advocating is that technical writers verbally call this mentality "Object-Oriented Documentation" or "OOD." Before I was laid off, I used Confluence in the way this post describes. Our team came up with the idea of including screenshots in an expand / collapse section. We reasoned that doing so would serve both those users that know what they are doing and don't need the screenshot and those users that don't know or are unfamiliar with the tasks they are doing and do need the screenshot to verify that they are in the right place. I know our department didn't invent this methodology - I'm not claiming we did.

The beauty of this OOD mentality is quite simply awesome. When there was conceptual information that needed to be in multiple places, we created a page with just that content and referred to it from the pages that needed to have it. In this way, both written word and screenshots that were referred to in many places could be updated by simply updating the page that was referred to by those other pages.

Tuesday, February 10, 2015

Twenty Years

I spent some time this AM reflecting on the ups and downs of my career earlier today? It's my 20 year anniversary of working as a technical writer. Twenty years ago today, I had an interview @ 8 AM at a company that does not exist by the name it had in 1995. By noon, I had signed my job offer letter. Starting salary? $18,000. Only 5 permanent employers over 20 years:
Job # 1 was 3 years
Job # 2 was 7 months, 2 weeks, 6 days - Left there after 3 years to go to a place that had $ issues and by 10/1/98,
Job # 3 was 12 years
Job # 4 was 6 months, 5 days
Job # 5 has been 3 years, 8 months, 1 week, 3 days

I hated Job #4. I don’t talk about it much even though I’ve bitched about that place elsewhere on this blog. My co-worker - the senior member who was a b*tch - made me write:

From File, select New....

Why? The menu option under the File menu was, yep, "New..." and the doc had to match the UI exactly. When I asked her whether to use one or two spaces after a period, she said to me, "Use one unless it looks funny; then use two."

She also thought that it was better to manually type the TOC for a 150ish page user guide and print it out iteratively as changes were made. When I suggested implementing styles into the tool we used (her choice was InDesign, probably because she came from the Marketing dept years before I arrived.), she declared that it looked too complicated. InDesign was not even close to being used "properly" - it was essentially a Word doc in Normal style with manual formatting applied. There was nothing that was being done in those awful docs that couldn't have been done better (and faster) in Word.

I am happy where I work; I look forward to a long career here.

Sunday, December 7, 2014

Frag the Simpest of Tasks

I love the way Ed on Techwr-l strung words together when he wrote:

I worked with writers who could frag the simplest of tasks. The conclusion I've come to is that we need some skill, but also must want to get better at it.

To which I replied:
I agree with what you wrote below. I briefly worked at a hellhole for a few months in a department with a writer that had come from Marketing before I arrived. She insisted upon using InDesign to write a 100+ page user guide. InDesign (ID) *could* have been the right tool, but she refused to use its capabilities.

  1. She wouldn't use styles to automatically create a TOC, brushing it off as "too complicated". She wouldn't comprehend that my suggestion would avoid the horror story she told me about manually typing the TOC, printing it, and then verifying, by hand that the TOC matched the actual page number, and staying until 11 PM the night before a deadline to make sure the manual was done on time.
  2. She required a line be drawn next to each heading from the last letter of the heading to the right margin.
  3. She used empty paragraphs to control formatting.
  4. When I asked whether the department standard was one or two spaces after a period, she told me, "Use one unless it looks funny, then use two."
It's very difficult to say anything positive about those months. Thankfully, I'm at a much better employer, approaching my 4 year anniversary in May 2015.

Saturday, November 22, 2014

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.
    • 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. 
    • Soft skills
    • 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. 
    • 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.