Without Structured Authoring, You May Be Working Too Hard

It’s the old adage – don’t work harder, work smarter.  This especially applies to content developers.

With the endless demand of taking products to market that meet specific needs of the customer, there’s never been more of a demand for documentation that helps the customer solve problems, save time and prevent operations downtime.  I’ve never met a product developer that wants to be a wrench in the works; and let’s face it, documentation in some form is almost always part of the overall deliverable.

The fact of the matter is technical documentation content creators don’t start from scratch every time.  If you’re currently doing this, read on!

To keep from re-inventing the content wheel each time with every new document, here are a few tips to break free of old thinking:

• Think about what written content already exists, and plan around what you already have.
• Your documentation isn’t your own (it’s the company’s property), and it doesn’t need restated different ways to convey the same message.
• Re-stating the same message different ways isn’t uniqueness – it’s duplication.
• With good content planning, you’ll see the advantages of content re-use.

If you are re-using a lot of content, structured authoring can provide:

• Content in small re-usable chunks called topics
• Less of a need for edits because smaller topics often require less maintenance
• A depository of pre-prepared content, which is an organizational asset
• A design to the content (structure) that is built around a planned model

There are concrete reasons why structured authoring is better than a simple cut and paste into a word processing document:

1. Your organization may have plans for documentation beyond the writer’s expectation. Remember that it’s not the writer that determines how the content is used long term.  Content developers should ready themselves to provide a content management system that can piece together documentation as the organization’s needs evolve.
2. Remember that every piece of content exists within a reusable context. Messages are built by associating contexts.  These are the building blocks of relevant documentation.
3. Structured content is sharable among work groups and others both within – and outside – the organization. It creates an easy to use, common format.

Best of all, stored content is searchable and can be recalled easily.  By recalling re-authored content, writers can use topics like building blocks to create documentation.  Perhaps the greatest contribution any employee can provide an organization is efficiency, and structured authoring offers us that opportunity.

Why the World Needs Technical Writers

To echo my previous post, the world needs technical writers.  Richard Rabil, Jr. makes the case masterfully!

https://richardrabil.com/2017/10/20/get-into-technical-writing/

Five Reasons Why Software Developers Need Technical Writers

It’s no small wonder why such a large percentage of employers offering opportunities for technical writers are in the software industry.  The apparent need for more clear, concise and generally better quality documentation has always been good news for technical communicators.  We’re here to do what developers have historically shown they struggle to do well.

Here are several reasons why developers need technical writers to improve their documentation

1. Developers hate technical documentation because it’s not in their wheelhouse

Developers often feel their writing skills are limited because their work isn’t centered around written communication.  Developers don’t need to center their focus around the needs of a document’s audience, they need to foremost focus on the needs of the software end user and the practical function of the product.

2. It’s an added responsibility

Developers have to answer for a lot – most importantly, the usefulness of their code.  Quality documentation – presented in a logical, planned format – is not their primary concern.  Often this sharing of responsibility with a documentation professional is a welcome relief.

3. Code Changes Too Frequently

Developers writing documentation once is a Utopian idea, but not realistic.  Good documentation incorporates frequent updates, and it is more accommodating for developers to feed information to writers than to process it into the documentation.

4. The push is on

The customer pushes the company, the company pushes the department and the department pushes the developer.   With a due date constantly looming, developers constantly need more time for coding, and less time for documentation.

5. Developers are Living Inside their Code

Developers are often occupied with the product’s function, and less concerned with the need to explain things clearly.  Fortunately, technical writers have spent years honing skills and techniques needed to create usable content.

Believing developers are most suited for creating technical documentation is a short-sighted view.  Customers will always need documentation with product delivery, and are best served by documentation created by people best suited for the job.  I’ve seen instances where developers waited until the last minute to produce accompanying documentation, and the results were disastrous, usability was low and the end product quality was affected.  Remember – there is always a chance customers will return the product because of poor documentation.  Is there any doubt the skills of a technical writer are part of the solution?

Your Sunday Funny!

Can you relate?  If so, drop a like to this post!

Holiday Joy in July: Creative Gift Ideas for Writers

It’s not too early to begin thinking about the holidays.  Here are some really creative gift ideas for the writer at the top of your gift-giving list.  While most haven’t begun to consider 2018’s gift offerings, this list published a few months ago by The Write Life should help with ideas for the upcoming holiday season.

 

Avoiding Scope Creep in Technical Documentation

Jeepers it’s the Creeper!  You know – that uncontrolled growth in a project’s scope that spreads like a virus long after project objectives have been defined and agreed upon.  There are ways to avoid going down the rabbit hole and getting documentation off track.

Good technical writers keep in mind the goal of the document at each authoring stage.  That’s not to say extra details aren’t helpful, but too many of them can cause the scope to creep.  Here’s how to avoid creating unnecessary work that ultimately negatively impacts the value of the documentation:

1. Let colleagues suggest valuable information, but don’t let it get ahead of objectives. Remind everyone of the agreed upon content from the beginning of the project.  If the added content is an absolute must, consider an appendix.
2. Keep communication among parties open, and mutually agree and recognize that scope creep can be a project risk. When colleagues argue that the added content is “value for free,” especially in already lengthy documentation, remind them of the main objective and the risks associated with complicating important messaging and content.
3. At project inception, make sure that teams are properly identifying what is most important to achieve, and define a clear and mutually understood roadmap on how to achieve objectives. This is best attained by practicing methods of concise and relevant document planning.
4. Assure that after the project plan is defined, progress is documented and controlled. One method of control is referring to budget constraints.  A writer’s time comes at an expense, whether its an issue of time or financial resources.
5. Don’t think that one little change won’t matter. Think about it:  how is “little change” defined?

Finally, consider adopting a statement of work as part of the documentation plan.  It’s something that can be referred back to.  Consider it a team contract.  If possible, when additions to the project are absolutely and unequivocally necessary, allow changes to the statement of work by only a few authorized individuals.

Finally, remember the impact scope creep can have on a planned deadline.  The best way for your team to be successful is to produce top quality deliverables on time, on budget, and on-track for proper usability.

Thoughts on my Favorite Wordsmithing Quote

“The most valuable of all talents is that of never using two words when one will do.” – Thomas Jefferson

There’s no doubt that Jefferson penned some of the most important works in American history.  He is most recognized for writing the first draft of the Declaration of Independence, and Notes on the State of Virginia has been called the most important American book written before 1800.  Ironically, in drafting the document declaring independence from Great Britain, Jefferson didn’t take his own advice.  History shows Congress edited Jefferson’s primary draft, removing unnecessary wording and shorting it by nearly one fourth.

There’s plenty writers can do to combat wordiness and preserve the life and liberty of our content.  To trim the redundancy, consider the following:

• Remove unnecessary phrasing, as in shortening “the person who works at the check-out” to simply “the clerk.”
• Remove introductory words such as “actually.” In fact, do us all a favor and use that one less in conversation.
• Remove linking phrases such as “I need a ticket in order to enter the theater” by shortening to “I need a ticket to enter the theater,” or even better, “a ticket is required.”
• Remove entire sentences where possible. For example, “Next, I will discuss the manufacturer’s recommendations for caring for your new car.”  Eliminate the sentence and just get on with it in the next paragraph.

Whenever possible, consider sentence structure revisions for more concise copy:

• Avoid passive voice. I’ve been writing for more than 30 years, but I still catch myself doing this.  Don’t say “the program was organized by the directors” when you mean “The directors organized the program.”
• Use simple past/present tense to be more succinct. Don’t say “I have delivered pizza for more than a year” when you can say “I delivered pizza for more than a year.”
• Don’t say “There are many components that make up the control system” when you mean to say “Many components make up the control system.”

Although Jefferson didn’t always take his own advice, his comment about concise writing being the most valuable of talents still rings true centuries later.  No wonder he’s referred to as one of the leading spokesmen for our nation’s democracy, and an important communicator of new social and political ideas resulting in America’s independence as a nation.

De-scrambling the Creative Process: 5 Steps to Laying a Golden Egg

The Beatles’ John Lennon and Paul McCartney are known as two of the greatest song writers of all-time, and for good reason.  The Beatles have remained always relevant, even generations after they first wrote songs in the early 60’s.  They achieved this pinnacle of song writing success because they knew how to navigate the creative process, and turn simple ideas into gold.

Paul McCartney

Perhaps one of the most celebrated songs of their career is Yesterday, a tune with a flowing chord progression and melody that came to Paul McCartney in a dream.  After waking, he had the song’s musical structure, but the lyrics were missing.  With his creative process in full swing, he first wrote the words “scrambled eggs” to establish a working syllable pattern.  What eventually became “Yesterday…all my troubles seemed so far away” began as “Scrambled eggs…oh my baby how I love your legs.”  Paul’s example shows us all as writers that sometimes all the creative process needs is a placeholder.

The creative process isn’t an insurmountable obstacle.  To be creative, you must first be a problem solver.  Just as a sprinter must clear hurdles on the way toward the finish line, the writer must face obstacles along the path of generating a great idea.  From my experience, here are five steps that will help lay your golden egg:

1. Follow the Scouting motto:  Be prepared.  Take time to research all aspects of the message you are trying to convey, who you are trying to convey it to, and all relative information surrounding the topic.  Attempt to learn something you may not know about the topic.
2. Take time for introspection. I believe the keys to navigating the creative process are understanding ourselves and others.  Consider how others would view your subject, and how their perspective motivates or shapes your view.  If you need to go for a walk, exercise or take a break to step outside your own limitations, do this to better focus yourself.  One technique I use is to try to think of something funny about my subject, and laugh out loud about it.
3. When you reach your “A-Ha!” moment (when your golden idea appears), you’ll know it’s the perfect approach, and you won’t want to do it any other way. Immerse yourself in your idea, and build around it.  Make it relatable to your audience.
4. Develop your golden idea by sharing it with others as a test audience. It doesn’t necessarily need to be an organized test panel – just a few people who can provide valuable input.  “John, I’ve got this idea for a song called “scrambled eggs….”
5. Run with it! Put your idea into a final format, promote and advocate your idea, and send it out to the world that is meant to see it.

This is – by no means – a comprehensive list.  What techniques work best in your creative process?  What are your obstacles, and how do you overcome them?  Drop me a comment to share your own tricks of the writer’s trade.

Next Up:  Three Tips to Help Writers Avoid Procrastination and Save Time

The Devil is in the Details: How to Become More Detail-Oriented

The Muse is one of my favorite sites for browsing for employment opportunities and finding great advice for upping your game at work.  President and Founder Alex Cavoulacos offers some excellent tips for greater attention to detail at work.  Checking for consistency especially rings true for professional writers.

As Alex mentions in her bonus tip, always check for tpyos typos!

Check out more of Alex’s interesting articles on The Muse.

 

Willy & the Word Jive

I grew up an only child in a small Western Pennsylvania town on the Ohio River just about 11 miles west of Pittsburgh.  Like most people, I don’t remember much before the age of 3.  When you’re that young, the world is small.  You have your family, your toys and your neighbors.  Our neighbors next door had a full household with three daughters.  The youngest daughter, Patty, was about ten years older than me, well into her teens.  In the summer of 1974, it wasn’t long before word was getting around the neighborhood that Patty had her first boyfriend.  The object of her affection was Willy, a tall, athletic, well-dressed and quick-witted guy with a red convertible with a white interior.  He would pick Patty up for dates in the early evening, and wave to me as he drove by with a “Hiya Richie!”  All the neighborhood kids thought Willy was a cool dude.  Years later, Willy and Patty married, and Willy became the English teacher at my hometown high school.

When I reached high school age, I became one of Willy’s students in his Basic Composition class, which eventually became my favorite course in all my years of school.  Willy is the first person I remember knowing who had a strong command of the English language.  He handled words like some folks hand jive.  He was quick with synonyms, could turn over a definition in no time flat and had a quick rolling rhythm about his writing.  I’m sure that Willy’s class had the usual activities of any American high school, but he did one memorable thing in an effort to improve our vocabulary and word choice.  Each day as we entered class, we would find a “Word of the Day” written on the board.  The first student with a definition and could use it in a sentence would be rewarded with a candy bar.  Needless to say, it got quite competitive.

I can’t pass candy through your computer monitor, but in keeping Willy’s tradition, your word of the day is Contemplative, which you’ll recognize from my blog’s user name and social media identity.  I believe all good written content begins with introspection.  Before putting pen to paper, we as writers must take plenty of time to consider our audience, craft a message that speaks to our readers and find ways to be memorable.  Like the Word of the Day.

I ran into Patty and Willy recently, and I asked him “What ever happened to that red convertible?”

“That old piece of junk?” he asked.  “I had to turn the radio all the way up to keep from hearing the engine knocking.  It was ‘clamorous,’ and there’s your Word of the Day!”

The convertible wasn’t as I remembered it.  Maybe it was his way with words.

Who is the first person you remember for being an inspiration for your writing and passion for the English language?  Drop me a comment!

Next up:  How to become a more detail-oriented writer