Special Announcement for TechDocs Future

TechDocs is excited to announce that we have successfully acquired our first government contract. This contract is a Blanket Purchase Agreement (BPA) for five years, and we will be providing services to 27th Special Operations Wing Inspector General (27 SOW/IG) based at Cannon Air Force Base.

TechDocs has always planned to enter the Government contracting arena as we have a lot of experience working with military and civilian leadership. Challenges are often fast paced with a lot of visibility, which works great with our documentation environment. TechDocs is looking forward to building a long-term relationship with the IG’s team and contributing to their mission.

Determine the User - Quick Guide

The biggest question when creating documentation and content is who is the end user. Think of the end user as this mystic being that you know is there but may never interact with. I know, a crazy way to think of it, but it is true. Much of the documents/content we create will reach users that were never intended. Think of the last time you found some information that was way too technical or did not provide any background/context. It is obvious that the information was not intended for you but for someone with a more intimate knowledge of that subject. However, you still ended up finding the information and trying to use it for your purpose. This is the challenge of creating content and determining who the end user will be.

The first step is to look at who the intended audience is. This can be an executive, developer, your supervisor, and so on. Once this is determined, think about who could this content also go to. Maybe the information was intended for a developer but was then forwarded to the CFO for budget approval. If strictly created for the developer, the content will be difficult for the CFO to get a full grasp of the information without a Subject Matter Expert (SME) to translate. This could result in a project not being approved solely because of miscommunication. Along these lines is also cultural considerations for teams that are spanned across the globe. Word choices and cultural considerations will affect how the content is created, displayed, and understood.

So how do we solve this? Understand the project cycle and/or work environment. If management must always review/approve technical content being created, ensure the content is both technical for developer use while containing context to the technical information to get non-tech people up to speed. This can be accomplished by utilizing appendices for highly technical content, and the main body has a mixture of both technical and informational content. As mentioned earlier, we will also need to take in any culture considerations within the work environment. Certain phrases or content layouts may have different rates of success when it comes to understanding the information created. The best way to handle this is to work closely with teammates from those areas and receive review feedback on the content you are creating.

Next we look at how the content will be transmitted. Is the information sitting on a sharing platform, printed manual, help system, etc.? All of these mediums could change how the content is created. If the content is commands for a developer, a Quick Reference Guide (QRG) one pager will be appropriate as they may print it out to have on their desk. A help system would need to have both highly technical information filled in with introductory information as not only SMEs will access the information, but also professionals wearing multiple hats. Technical writers will know the request of being the writer, and the QA engineer, and the code debugger, etc.

The last portion is where the content is housed. Will this be on a public facing site for the world to access or on a limited access subnet within a Virtual Private Cloud (VPC). Information for the world, especially help or do it yourself (DIY) type information, will be less technical heavy so users can understand and troubleshoot any issues. Items in a company’s secured database could be based on the types of user access to that content (i.e., dev area is highly technical; more introductory information for average user access; and slides with bulleted information for leadership).

User analysis is a difficult part of content creation to nail down. We know who the information should go to; however, it usually will end up in someone else’s hands. There is no way to consider all possibilities, but we can make educated determinations based on the environment the content was created in and how the information will be transmitted.

Let us know your thoughts or suggestions.

Visual Design - Color

From our poll last week on LinkedIn, we found that people did not really consider color important. However, color is an important aspect for all types of communication. For documents, it lets the user know when an action could injury them or break a component. In digital realms, color will make us feel and experience memories from our past. Color is a powerful tool when communicating with an end user and can determine their thought process going into a document or using a tool. Just think of the last time you worked with a product with awful color choices; your opinion is negative from the onset and will reflect in the usage of the product.

Color is something that technical communicators often have to consider when creating documentation. Here are just a few considerations from the start:

• Company branding

• 508 Compliance

• Which colors for warning, caution, and note

• Costs associated for printing (if applicable)

• Bandwidth and resolution if a digital product

• Tone and feel to relay to the user

• How much color to use as to not distract

A miscue on any of the above bullets could fail a project before going to the customer, or even worse, fail once the customer uses the end product. A company that takes color considerations seriously is none other than Apple. Here is a good site for their breakdown of color usage:

https://developer.apple.com/design/human-interface-guidelines/ios/visual-design/color/

A lot of tips from this site could be directly applied to the technical communicator, especially with more deliverables being created in the digital/mobile realm.

How does your company handle color in their products? Is color considered from the beginning or left as an end thought? Let us know in the comments.

Technical Writers: How Our Greatest Ability Can Work Against Us

Technical writing/communication is a very interesting field. The Society of Technical Communicators (STC) defines our profession with the following:

Technical communication is a broad field and includes any form of communication that exhibits one or more of the following characteristics:

• Communicating about technical or specialized topics, such as computer applications, medical procedures, or environmental regulations.

• Communicating by using technology, such as web pages, help files, or social media sites.

• Providing instructions about how to do something, regardless of how technical the task is or even if technology is used to create or distribute that communication.

STC also adds in all the titles we could possibly be labeled as:

• Technical Writers & Editors

• Indexers

• Information Architects

• Instructional Designers

• Technical Illustrators

• Globalization & Localization Specialists

• Usability & Human Factors Professionals

• Visual Designers

• Web Designers & Developers

• Teachers & Researchers of Technical Communication

• Trainers and E-Learning Developers

When reading through this list, one has to think that is impressive. I have been in the field for 12 years and can say not one job was like the other. Each new position had different requirements, with different software, on different networks. You kind of see where this is going. It is almost like being that new guy to the field for every first day on the job except you are a seasoned professional.

So are we like the X-men of the professional realm, out to help in any situation? No, but that would be pretty cool. I have found most technical writers have one core ability that makes us amazing at what we do. It is the ability to adapt quickly to an environment and/or technology. We often go in to a new position without much prior knowledge of the proprietary technology we are about to document. On the government side you have military leadership that changes out frequently, adjusting or eliminating the courses of action (COAs) from the previous commander. Even with these roadblocks ahead of us, technical writers are expected to “hit the ground running” as they say and be able to breakdown a system/concept into something digestible for the end user.

I personally see this as an amazing feat of adaptability, as I have been in the position where I took on developer and system admin roles (basic) because the team needed a hand with a project. I had no previous knowledge of the tasks I was to be overseeing; however, I was expected to learn. In some instances, I became a subject matter expert (SME) on the system. As a company owner, I find this trait indispensable because this means I can rely on this professional no matter what project comes to TechDocs. I am not just talking technical writers either; I have worked with talented developers who could pick up/learn new code on the fly to make a project work.

Unfortunately this ability is seen differently by companies based on whether the professional is a technical writer or developer. The developer will be held in high regards as someone who can jump from projects and fill gaps in application development where needed, even if they need some time to spin up on a new language. For technical writers, we too can be held in high regards. I have been fortunate enough to be on great teams that allowed me to show off my potential, often receiving kudos by our customer. Our customer is behind me and my work; my team is behind me and my work. So where is this downside to adaptability.

My experience has shown that adaptability for the technical writer can often result in being expendable during contract renewals/losses. Now don’t get me wrong, many professionals can get cut during contract renewals/losses. Companies do indeed take notice that technical writers have this amazing ability, which in turn makes the current technical writer expendable based on the fact the company can get another one at a lower rate, less need for flexibility, etc. I was laid off four times in a five year period while developing high quality documentation that was receiving kudos from leadership. In some cases, I was the only documentation person for the whole organization.

As mentioned earlier, companies will often find they can replace senior writers (require higher pay/more flexibility due to family) with more entry level ones who can adapt to the company’s needs just as well and not need those extra perks. I believe this is a bad choice as the seasoned writer carries tacit knowledge about the company’s documentation and processes. A new writer would need to learn these, which could hinder the document process in the long run. Another way our adaptability works against us is by companies thinking that if technical writers can do it, so can the developers. This results in the writing staff being reduced/eliminated, and the documentation jobs are now passed to the developers. There is nothing developers like more than spending time writing documentation (sarcasm). The final issue that can arise is the companies not seeing us as fully knowledgeable in the arena they operate. The old saying goes, “jack of all trades, master of none.” In a sense we have to be a jack of trades to be competitive in the technical communication field, especially with the number document/collaborative applications, markup/coding languages, and graphic design programs. It is impossible to know them all but is a must to certain employers. Because we are not SMEs, we are seen as a position that another could slot in and pick up where the last left off.

I do believe our ability to adapt and learn anything quickly is an impressive talent for technical writers; yes, I am somewhat biased. It should not be looked at as a negative since most other fields with this skill set would be seen as indispensable. Technical writers are crucial to an organization, especially in fields with complex information that needs to take the end users’ lack of knowledge into consideration. I will continue to be dumbfounded how one of our greatest assets can be turned against us when there is so much more benefits that come from our abilities to adapt/learn on the fly; however, maybe as tech become more and more relevant in every aspect of our lives, companies will see the benefits as us technical writers do.

Have you had a different experience with regards to your ability to learn on the fly? Is there a point I missed? Let us know in the comments below.

-Chris

Can Technical Documents Have Flare?

When most people hear technical writer, they automatically jump to “they like to write.” Yes, writing is a large part of the job. Technical writers often have to take complex ideas and break them into digestible chunks for the end user. But this is just part of the document creation process. Our job is to engage the user and only having blocks of words on a technical subject will make a user close a document quickly. They key is to not only inform the reader in a concise manner but also keep their attention through graphical means.

This is by far my favorite aspect of the field. Document and information design is almost an art. What colors to use and when, where to take the reader’s eye, and actually keep them wanting to return to the document when needed. It sounds simple enough: add some colors, screenshots, and boom you are done. I wish this was the case. Let’s look at the Apple Watch. If you’ve ever opened this product, it looks and opens like origami. Even the technical documentation (aka instructions) are minimalist, using a lot of white space, color graphics, and concise instructions. This is a good example of bringing a style of flare to a technical document. Marketing materials for technical products are another example of technical documentation having lots of flare. Usually there’s vibrant colors, multiple fonts, and graphics to catch the eye.

Now flare does not have to be limited to Silicon Valley or marketing products. Even something as dry as virtual machine deployment guides can have flare to them. Here are the steps we take to liven up technical documents:

1. Could this be a quick reference guide?

   Sometimes information does not need to have six pages in total just for a page or two of content. If the content can fit front and back with high quality graphics, then try out a quick reference guide. Also incorporate corporate colors/logos of your company or the customer. We find customers love these as it’s simple to hand out, less printing costs, and point out the essentials.

2. Use graphics.

   Nobody likes to see just text, especially when it comes to technical information. Most people would rather figure it out for themselves. Ensure the technical documents have high quality graphics (PNG) to accompany the important/confusing steps in the process. We still come across technical documents from major manufacturers where the menu items are fuzzy and/or too small to read. This will not help a user. If there are a lot of menu items or code within a screenshot, you could always highlight or box out the information being referenced in the steps.

3. Structure the information.

   As mentioned earlier, structuring information is sort of an art form. With enough practice, however, you can learn what feels natural for eye movement. One consideration is how the language is read. English is from left to right while Arabic is right to left (text), which can affect the placement of content. We have found success by starting in the top-left with text (English readers) and have graphics to the right. After that, each group of procedures alternate almost forming a snake type pattern. Modern designs also include blocked areas using color to differentiate processes.

4. Colors

   Seems self explanatory but we have seen some interesting color combos here at TechDocs. Companies typically like to their colors on documents, so this is always a good start. Logos can also be used to make the branding complete. To prevent distractions to the eye, usually you will see the headers and footers given the most color treatment. Colors can also be used to point out information like “Tips,” “Warnings,” etc. We recommend avoiding any colors that would be harsh on the eyes….sorry, no unmellow yellow for you crayola fans.

5. User Tests

   Yes, this is important. No matter how well you think your layout and color scheme looks, the customer might not agree. Remember, technical writing is a very subjective field. It is always best to come up with some drafts of the design and run it by the customer first. This will save everyone time and money. If it is an incredibly quick turnaround—24hrs or less—then we would recommend multiple versions to pick from. You may not have the perfect setup, but at least the customer can determine which way is the path moving forward.

We have mentioned how technical documents can indeed have some flare and provided some tips to do so when you are faced with having to create a technical document. TechDocs always try to make our documentation engaging for the end user as that is the best way to ensure they get the information they need. We hope that others will follow this thought process when creating their documentation and refrain from the blocked text approach.

Have you seen really good or poor documentation? Link us in the comment below. We would love to see what has caught your eye, whether good or bad.

Technical Writing in Private Industry vs. Government

Technical writing can be found in every sector of public and private industries. The reason is that everything has to be documented. Now don’t get me wrong, has to is different than actually doing. Many professionals feel they have it in their head and that is good enough, which works until they leave for a new opportunity. Then leadership runs to the technical writer to locate documentation that was never created. So now we circle back to everything needs to be documented within an organization.

Having worked on both the private and government side of technical writing, I can say the worlds are vastly different. The private sector is where most technical writers, in my opinion, would rather work. Often companies are more willing to experiment or take their documentation to the next level. They will have legacy documents in Word and Acrobat formats but want to get more from documentation. This will often fall into the realm of structured documentation. Wikipedia states a structured document is an electronic document where some method of markup is used to identify the whole and parts of the document as having various meanings beyond their formatting. In a nutshell structured documents are marked up (usually XML) and pieces of the document can be repurposed due to this markup.

Software to create structured documentation is often quite expensive for a license, and customization of applications like Arbortext can run into the millions for large companies. Even with these large costs associated with taking documentation to the next level, private companies will often take this chance to offer a better document product for the end user. Private companies will also find the cost savings associated with being able to repurpose documents for multiple uses. The fact that companies will take the time to incorporate higher tier software into their document process benefits the writer as well. The technical writer will now learn markup languages, software often used for high paying positions, and be in step with the current technologies.

In addition to structured document software, a lot of private companies are moving/already using collaborative component content management systems (CCMS) like Paligo. I know a lot of people will think of SharePoint as a collaborative environment for documentation, but SharePoint is very limited when compared to a CCMS. Trust me, I know with my attempts to inject code into SharePoint to push its boundaries. The CCMS allows for beginning to end document creation while keeping the theme of repurpose.

Now let’s take a dive into the government side of the Technical Writing field. I have a special place in my heart for the government side as some of things you get to see and document will help our troops in the field, create better policies, and the numerous other great things that come from what we do at the public service level. With that said, government technical writing could restrict your movement in the field. The reason being is that the government is about a decade behind the private sector when it comes to technical writing. Now this is coming from someone who worked at the DoD/COCOM levels of government. Maybe state and local government agencies or NSA/DIA may use more up-to-date technologies for their documentation. Government tends to use the old reliables, PDF and Word. This does not bother me as I am an expert in both and have often pushed both beyond their initial capabilities to make leadership happy.

Some of the documentation within government is so primitive that custom styles are not even incorporated into the Word documents for policies and memorandums. When it comes to documentation, the government takes the approach of not broken don’t fix it. I can understand this approach as their documentation needs are basic and there really isn’t an infrastructure in place to create an advanced document process without a lot of work. SharePoint is used as a collaborative tool for creating, editing, and signing documentation; however, due to security restrictions, you cannot as a technical writer inject code in the SharePoint environment to make it more robust. You would think this is the government and they should have unlimited resources for technology when it would benefit them. Well I have fought this battle at multiple locations, having my proposals for the incorporation of structured documentation declined every time. So how come?

There are two reasons: budget and security. The government likes budgets—believe it or not—and documentation is not a high priority to modernize within an organization. The great thing is the government likes to document everything, but Word and Acrobat is just fine for the job. Even trying to obtain one license for new document software is often declined due to cost. The next reason is security. Much of the latest and greatest documentation environments run on the cloud. Think of Adobe’s suites all being CC. The government can’t just connect to a public cloud due to the sensitivity of the documentation created. Likewise, companies using cloud for their software would not be able to push updates to users on a government network because of security protocols. This creates a huge headache to even attempt on multiple levels just to have some higher functioning documentation, and most GSs won’t take it on because of this.

Remember how I mentioned the possible restriction of your career working for the government as a technical writer? Think of it as being an actor that is typecast for that role. I am a fan of mobster movies, so who comes to mind: Robert De Niro and Joe Pesci. I know they have done a lot of other movies, but that is how I see them. The same can be said for technical writers who spend a long time in the government. While great at our jobs, we are mostly using Word, Acrobat, and SharerPoint. These software restrictions will also be seen by potential employers who want writers that can markup and/or code documentation or be familiar with the latest collaborative software. I personally have been passed up on positions due to not having hands on, production experience with the latest tools even though I could easily learn them. Us technical writers are great at learning on the fly. This is one of the biggest downsides to working as a technical writer on the government side, especially if you are in an organization that does not value the latest software for content creation. As a technical writer, you can always help yourself by downloading the software and trying it out after hours, but I have found this does not replace experience while on a team.

Working for a private industry or on the government side in the technical writing field can give you completely different experiences. By no means is one greater than the other; it should be based on what you prefer as a writer. I am hoping one day that government organizations will put more effort into stepping up their documentation game to compete with the private sector. While it would take some time and budget rearrangement, it would be very beneficial and save the government money in the long run. I also hope that private companies can look past us government writers to see that we can easily adapt to their “more advanced” documentation process. If you have had different experiences or see the same thing as mentioned above, let us know in the comments.

-Chris

The Evolution of Technical Writing

Technology has been intertwined in our lives for the last several years. Whether through social media apps, YouTube videos, or what ever other “latest and greatest” content creation platform, people are preferring these means to gain knowledge on both an entertainment and professional level. Whether you love him or hate him, Gary Vaynerchuk often delves deep into the power of social media/content creation and technology to help end users consume content. Our phones alone are portable computers, which we use to look for information. So how does this affect us technical writers?

Let me give a brief background. I have been in the Technical Writing field (IT focused) for almost 12 years now. I have held positions within secured facilities, training institutions, and publicly traded companies. These companies ranged from Fortune 100 to small business subsidiaries with a staff of 15. All of them have one thing in common, documentation. Ninety-nine percent of their documents were Word and PDF files. Now this is not based on when I entered the industry in 2009; this is how things are today. With the exception of some smaller, tech companies moving towards structured documentation or using platforms to create documents (e.g., Confluence, Paligo, etc.), most companies have the traditional documents we all love to hate—especially if you’re a frequent Word user like me. You would figure with all the “legacy” documents and software that technical writers would not need to worry about communicating through these “hot” mediums. From a 30k view, this may be the case. I believe there will always be legacy type documentation that needs to be edited/updated as long as there’s Word and Acrobat, and this is why part of the services my company offers focus on these platforms.

However, the reality is technical writing is evolving. Although you can find 100s of technical writing openings, how many are looking for the straightforward writing and editing that many writers are familiar with; very few are. Me being an IT technical writer, job postings will often require at a minimum to have a vague understanding of code, develop fully functional sites, and/or perform some duties usually performed by entry level System Admins or developers. That’s right. Coding and some basic system troubleshooting. Not quite what I learned in my English classes. Technical writers in a technology based field have now become required quasi developers. Personally I’m always up for learning new skills including coding, networking, and other more tech heavy responsibilities, but I find that this could be a shock to those who have been in the field for a while and enjoy just the writing aspect or the students who take technical writing courses that are not focused in what is happening within the Industry.

I have also seen this change happening in other technical writing areas like pharmaceuticals, healthcare, and training. These areas I will often see requirements that go beyond documentation, as if employers are looking for seasoned professionals who can also write. What I tell people is employers in IT want a developer who enjoys writing; good luck finding that. As a note, there are still positions out there that is strictly just writing. These tend to be fewer and fewer from what I am seeing in the Technical Writing field.

So it appears technical writing is indeed evolving away from writing in the traditional sense. I believe in the next 10 years we will see technical writer as a description gone and replaced with the term technical communicator. I understand that the term “technical communicator” has been used for a while now—long time follower of STC—but employers will start adopting that phrasing as well. No longer will we be relegated to only writing but expected to be a subject matter expert (SME) in what ever field we are communicating in. Position requirements will focus less on documentation, or writing aspect, and more on the communication component through different mediums like code, video, and even gaming. Technical writers already wear many hats within an organization to stay relevant, and I see this only becoming more commonplace as technology enter every aspect of end users’ lives.

-Chris