Technical Writing essentials

    I want to share some of my learnings starting from the beginning days of my Technical Writing career. Everyone in the project must have a cursory understanding of the following, and the Technical Writer must understand it in detail:

Language standards

Learn the style guides. MSTP (Microsoft Manual of Style - currently called Microsoft Style Guide) is among the most widely followed style guides. You can access it online for free and even download the PDF for offline reference. See https://docs.microsoft.com/en-us/style-guide/welcome/

There are several other style guides, but it is mostly enough to refer only to Microsoft Style Guide. The following are some of the key takeaways:

• Avoid passive voice - sentences in passive voice are generally longer and harder to read.
• Use only the simple and easy words understood by the global audience with varying degrees of English knowledge. Your writing must have the same meaning for all people from different geographies and cultures.
• Never use any idioms in your writing. They have subjective interpretations, and non-native users of English may not understand them correctly.
• Avoid gender bias in your writing. Do not assume that the user is only male or female. Do not refer to the user as 'he' or 'she'; using 'he/she' instead is allowed but not recommended.
• Expand an abbreviation on its first occurrence.
• Use correct UI terms.
• Avoid redundant words.
• Keep sentences short for better readability.
• Chunk the information - apply information mapping. It is easier to interpret a table, list, and chart than big paragraphs of information.
• Try to use parallel constructs in lists and instructions.
• Check for spelling and grammar errors and typos in your writing. Basic errors could erode your credibility as a writer.
• The sentence in a list can begin with 'the' for better impact.
• Check for missing articles; it is among the most frequent errors in writing.
• Use a comma before serial and serial or.
• Spell single-digit numbers in letters.
• Use short and crisp headings.
• Capitalize big words in a title.
• Apply correct styles. Remove the pre-formatting while using content from an external source.
• The documents must use version number and revision history to help keep track of the updates.
• Revise your writing till you feel you have got everything right. I suggest using a grammar check tool such as Grammarly. Even MS Word and Outlook does fairly good grammar check.

Planning and estimation

It is never easy to have accurate predictions. Planning and estimation in Technical Writing are among the trickiest things. Estimation is an exercise in making an educated guess. We often have wide deviations from the original estimates no matter how hard we have tried to avoid them. It is very often because of environmental factors. Sometimes the project itself is delayed, rescheduled, or shelved. The project scope keeps changing. 

Large projects will need multiple Technical Writers. Technical Writing projects have a shorter duration compared to development projects. It is not required to have a Technical Writer assigned to a development project throughout its entire length. A version increment for a product may take several months, but updating technical manuals may not take as much longer. The Technical Writer can spend effort on several projects during the same time.

Getting inputs and getting the reviews done is one of the biggest Technical Writing challenges. Be proactive in gathering inputs and pushing the documents for review. Spend time to build product competency and exploit multiple ways of gathering inputs. Minimize the wasted time to help your company and the project.

Manage your time better by knowing the peak dates for different projects. Start early on a project and have visibility for at least a couple of weeks or months in advance.

I believe Kanban is the most suited process for Technical Writing. Maintain the list of planned, to-do, and completed items. Try not to have more than five items on the 'to-do list. 

• The new planned items get added to the 'planned tasks' list, which is your backlog. 
• The 'to-do list' will have the tasks planned for execution. 
• The executed tasks will go into the 'completed tasks' list. 

Simplify the process as much as you can -

"Everything should be made as simple as possible, but not one bit simpler." - Albert Einstein

Improve predictability

Good planning increases predictability. A good plan ensures that the tasks are identified in advance and deligated appropriately. Someone responsible for it will be able to perform it with relative autonomy. No one is overworked o underutilized. There is lesser wasted work and rework, and we know the direction in which we are progressing.

Failure in planning would mean a lot of ad-hoc tasks, plenty of rework, and last-minute work. Engineers end up working late nights and still accomplish only the bare minimum. People will be demoralized and drained of their energies. 

Lack of good planning can become a compounding problem. Engineers working on such projects may get into trouble in their personal lives as well. They will have lesser time to improve their skills. The company/project may see a lot of voluntary and involuntary exits. It would hit the overall stability, and it would take a long time to repair the damage. 

Completion criteria

Updating the Technical Manuals must be included within the mandatory completion criteria for developing a new product or the feature. 

We bank on the Technical Writer to be savvy enough to do as much research by oneself as possible. The Technical Writer must try to install and configure the product. The Technical Writer will try all the different features, will try to understand the API calls. The Technical Writer will refer to the product-specific information available with the team. The Technical Writer will also refer to the publicly available information to learn about the standards applied, the external components, the hardware used, and so on. The Technical Writer's responsibilities include aiming to understand all the dependencies applicable for the product's functioning. The Technical Writer must aspire to find all the information which must go into a manual. But very often, the Technical Writer does not have all the resources needed for this at their disposal.

The product team must not abdicate the responsibility to give inputs for the manuals. Talk with the product management and the engineering management to make sure updating the manuals is a part of the completion criteria. Suggest having a signoff from the Technical Documentation team for the product enhancements.

PS: Technical Writing inputs as completion criteria must apply only to new features and enhancements and not for the defect fixes and known issues unless you have a large team of Technical Writers.

Document Development Life Cycle

DDLC (Document Development Life Cycle) consists of the following steps:

• Plan
• Structure
• Write
• Review
• Publish

Plan

Planning is a continuous process and will need frequent revision and changes. Planning indicates where we want to be, and even the best plans are subject to periodic revision. Identify the project goals during the planning step. You will need to identify the following while planning a Technical Documentation project:

• Deliverables - identify the key deliverables needed
• Audience - identify the intended audience for different deliverables
• Stakeholders - identify the key contact persons for the project
• Reference material - information sources such as SRS, FRS, hardware specifications, CAD diagrams, marketing datasheets, project backlog, product backlog, meeting notes, meeting recordings, project Confluence page, JIRA, Epic, etc
• Tools - identify the tools that you want to use in creating the deliverables
• Human resources - identify the members who are going to work on the deliverables
• Contingency plan - gather information on the availability of resources and try to have advance information on planned leaves and the backup resource
• Training - get training on the product, tools, domain knowledge, and others.

Structure

Identify the chapters, sections, and topics to include in each of your documentation deliverables. You can borrow the structure of a similar document and make changes to it to suit your needs. Consult the Information Architect, Product Owner/Product Manager, and any key SME (Subject Matter Expert) for their opinion on the planned document structure. The document structure can keep changing as your understanding evolves.

Write

This step involves writing the content. I suggest authoring the base draft of a new document using MS Word or Markdown, or any other word processing tool.

Consider content reusability

Structured authoring can help in content reusability. Try to author content as reusable chunks of information. DITA organizes content into concept, task, and reference.

Avoid pitfalls

Make sparing use of variables and conditional tagging. In other words, use it only where it is necessary. Too heavy use of variables and conditional tagging will make it harder to maintain the content in the future, and a new writer may find it hard to understand what we did. Split the document if required.

Revise the contents

The document structure identified in the earlier step may need fine updates as the writing progresses.

Convince yourself about your writing before convincing others. Revise the contents until your feel sure that it is in the best possible shape. 

Ensure the information is complete. Ask as many questions as you can, and try your best to find the answers by yourself. Explore all possible ways of ensuring that the information is complete to the extent possible.

Be savvy

No mistakes are allowed in a job when you have to earn your bread and butter from it. Writers hate criticism. Everyone can do the writing job, and at least people think so. You are an expert in it only if you are doing the best job in it. Avoid giving room for others to criticize as it can leave you demoralized.

Buy additional time if it is hard to complete the writing with good quality within the available time, and it is better not to be sorry later. The project team often perceives Technical Writer as an outsider, and Technical Writers always have an uphill task in establishing their credibility. The punctual and dependable Technical Writer with a good understanding of the product will have high credibility. It is harder to emphasize the need for language articulation and people skills in a Technical Writer. 

Take care not to assume that you will get help and push for it when needed. Your deadline is only your deadline, and the project team will worry about the documents only when they need them.

Demonstrating skills in the product and the tools will earn you points. Invest your time in knowing the domain and the product. A good Technical Writer does a lot more than just improving the draft shared by product experts.

Coming to my personal experience as a Technical Writer, writing the document by myself with little outside help is always the most gratifying experience. An engineer's draft can be my reference while I go all out to find out everything about the product to write about it.

Review

Writing and reviewing can go hand-in-hand. You can send the completed content for review while you continue to write the remaining content. Track the review comments and ask for additional information. Request for review meetings if required.

Share files using file hosting service

Typically, I share my files for review through Microsoft OneDrive. Using Microsoft Teams is also a good idea as companies have sharted using Teams now. It is always better to send the link to a shared location than to send a mail attachment.

Advantages of using a file hosting service

A single folder can contain all the files needed in a release. The bigger file size is not a worry and uses less bandwidth than sharing by mail. I can change the file anytime without sending multiple emails, and the reviewer also can place the commented draft in the same folder. 

Things not to do

Do not use JIRA for document reviews. I attach only the final document in the JIRA if we have a JIRA that tracks it. You do not want to be in the endless cycle of going to-and-fro and do not want to generate countless numbers of emails and notifications. Do you?

Online review

Reviewing online is the best way of reviewing a document. Have a meeting with the stakeholders and let them review the document during the meeting. Use a business communication platform such as Microsoft Teams for the meeting. Record the meeting to make sure that you have not missed any of the reviewer's comments.

Publish

Publish information in the desired output format such as PDF or help file. Most authoring tools support single-sourcing that allows you to publish the same file in multiple formats.

Check a few essential things before publishing the document. Make sure the document version number and revision history is updated. Verify that the table of contents and bookmarks are updated, all the hyperlinks and cross-references are working, the page numbering is correct, and a few other things may need checking. Get help from a fellow Technical Writer if you are stressed and fear missing something.

Ask questions

Lawyers, journalists, and doctors will have training on questions. An engineer who comes into Technical Writing will need to train oneself on asking questing. You get the information only if you actively seek it. Questions follow an inquiry in your mind. Like a good journalist, a Technical Writer will research a topic exhaustively and asks as many questions as possible. Asking questions is a skill that you can cultivate. The following are some of the resources that can help for the same.

• https://hbr.org/2018/05/the-surprising-power-of-questions
• https://www.dummies.com/careers/find-a-job/interviews/ten-tips-for-asking-good-questions/
• https://www.lifehack.org/articles/communication/how-amazingly-good-asking-questions.html
• https://www.entrepreneur.com/article/254264

The Technical Writing Process

The writing process has the following steps:

• Research
• Understand
• Plan
• Write

Research

Research your topic. It includes a critical analysis of what you are going to do and your way of gathering information. Connect the dots at this stage. 

Applying parlance with cooking, you are gathering the raw material at this stage.

Understand

Digest what you have researched. The idea is gradually turning into a concept at this stage.

Applying parlance with cooking, you have started cooking at this stage.

Plan

Plan the contours of your writing. It includes the logical organization of information and the document structure.

Applying parlance with cooking, you are readying your dishes to present to your guests.

Write

Do the actual writing. Make sure to follow the Technical Writing standards.

Applying parlance with cooking, you have served your dishes at this stage.

Document Structure

The document paraphernalia includes a header and footer with page numbering, cover page, copyright notice, and table of contents. A larger document may have an index and a list of references. 
Consider the heading levels correctly. A large document can use four heading levels apart from the document heading and chapter heading. A short can use two heading levels apart from the document heading.

Headings of the same level must follow a parallel structure. Topic headings can begin with a gerund, and task heading can begin with an infinitive.

Using Graphics

Insert a graphic with at least 300 DPI if the file goes for print. The screen meant for print must be captured with high resolution. 150 DPI may be enough for a graphic if you are not printing the file. Images in PNG and JPEG formats are preferred. Apply borders to make a graphic contrast with the background.

Always try to retain the original resolution for a graphic. Reset the image to its original size before saving it to the disk. For example, to reset the image to its original size in MS Word, right-click on it and select Size and Position > Reset.

Image naming conventions

Name images in such a way that they are easy to identify. Think of it as an SKU (Stock Keeping Unit) number. Derive a convention to name the image. Prefix the image name with the shortcode for the product, product version, product module/function, and the sequence of their appearance in the manual.

Master directory for images

Very often, we neglect the reusability of graphics and images. It is a good convention to have an image master directory. Place all of them in the master directory. Having a master directory for images will make it easy to reuse the images.

If you author using Markdown, it is better to have the images hosted online, and you use the image in your document by including the image link.

Images increase the file size and also will go outdated very soon. So, make sparing use of them. Delete those not used any longer will save disk space along with reducing the maintenance headache. 

Use relative path

Always use the relative path while inserting graphic items. Nearly all the authoring tools have this option.

Communication

Communication brings people closer. Give higher priority to one-to-one communication. I prefer not to write a mail for something that we can discuss in person.

Avoid harsh criticism of anyone, and avoid embarrassing anyone. Someone who erred in some way will need a face-saver to grow over it. 

Try to understand the background of the problem even when you do not like something about someone. Criticism makes people defensive. We very often assume that it is generally so in children, but adults are not different.

Recently, I was reading How to Win Friends and Influence People by Dale Carnegie. He says some of the biggest failures in human history are failures in communication. Some of the most successful leaders and entrepreneurs became what they are because of their communication skills than any other skills.

Communication is communication with oneself. We convey the meaning within us with others. You do not need reasons to be kind to others. You get the best cooperation from people when you can see their side of things.

Ownership of Technical Writing project

An experienced Technical Writer is someone who has spent years in the writing job. Every job has its unique challenges, and it takes years to know things in and out. Trust the competency and skills of your Technical Writer. It works to empower a Technical Writer. You may have only a few of them, and they carry the weight of all the documentation for the project/company on their shoulders. The Technical Writer must have the overall ownership of the Technical Writing project.

Technical Writers deserve the best cooperation from the project team. Very often, a Technical Writer has spent a relatively shorter time in the project compared to most other engineers. The project team may overlook Technical Writer in some discussions and emails. All this could be unintentional oversight, but remember that this guy is responsible for producing documents for the company, and the documents convey a significant portion of the company's brand image.

Technical Writers deserve recognition for their work. We neglect to praise someone when they do a good job and complain when something is wrong.

Allow people their process. Technical Writer deserves autonomy in their work. It is the most important motivating factor for almost everyone in the knowledge industry.

Adopt Proactive Approach

Believe in doing more than the bare minimum. Technical Writer should do everything possible to identify outdated and defective content, and this is one of the reasons for me to advocate less dependency on JIRA. Never write anything until you fully understand it. Quality in technical documents is the responsibility of the Technical Writer and not that of other product team members.

Herald your presence

Make the project team members feel your presence. Coming to me, I am an introvert by nature, and I fear that I will be left out. In my opinion, writers and public speakers are introverts by nature, and God has given you skills with words to compensate for the same! Even a lot of hard work can let you down if people do not feel your presence. Communicate what you did and how you did to make people recognize your efforts.

Handling conflicts

Writing teams very often have conflicts because of disagreements over the writing style. Writing is always a bit subjective. It is better to have guidelines and best practices than try to set rules. A friendly working environment is always more productive. People can have autonomy in their work and customize the process for themselves as long as it is consistent with the overall team objective.

Writing always has room for improvement. Encourage people to revisit their work often. Allow opinion diversity. A family, team, company, country, or nation can never thrive without tolerating differences of opinion. The different thought processes can help the company. Brainstorm the ideas and vote for the best idea.

Importance of naming the team

It is always better to have a name for your team. A name for the team helps in instilling a sense of pride in belonging to it. We give a name to our pet cat. Then why not consider naming the team.

Shared ownership of documents

Always be clear that the product documents have no single author or owner. Taking credits by putting the author's name on a product document is not encouraged, but everyone must get due recognition for their contributions. Be generous in giving credits than taking credits.

If the revision history of the document requires mentioning who authored it, give the team name there.

Technical Writing Tools

A Technical Writing tool can be either a structured authoring tool or an unstructured authoring tool. Structured authoring tools are generally XML-based. Arbortext Editor and Oxygen XML are the most popular XML authoring tools. FrameMaker is among the most popular authoring tools widely used by large and small corporations. It can do structured authoring as well. A few of the other popular tools include MadCap Flare and Paligo. Paligo is among the top-rated authoring tools in 2021 because of its friendly interface.

Several XML authoring tools support DITA (Darwin Information Typing Architecture) implementation. DITA is a stricter version of structured authoring, which segregates information into Concept, Task, and Reference. Several large corporations implemented DITA, but it may be losing its charm over the years because of its slow evolution.

You can implement structured authoring with Word and Markdown as well. It boils down to topic-based writing.

Topic-based writing

Topic-based writing focuses on the instructions to accomplish a task. The heading for a topic generally starts with an infinitive, which is in the format of 'To do ...'. Mention any prerequisites if required, and a series of instructions follow it. Document the instructions in steps, that is, Step 1, Step 2, etc. Use graphics if needed and try to mark it with step numbers to show the sequential instructions. 

Project Management for Technical Writing

The engineering Project Managers are primarily focused on the engineering deliverables and not on the documentation deliverables. Therefore, the Technical Writer must take an active interest in the project management for their deliverables.

The project management includes planning, managing communication, identifying dependencies, finding the availability of reviewers, time management, research on better tools and processes.

A single Technical Writer might be contributing to multiple projects. Clear communication and clever time management are a must.

Internal vs. External Documentation

Internal documents

The documents created for the company's internal audience classify as internal documents. The examples of internal documents include the Knowledge Base referred by the companies Technical Support team and the API guides for the company's internal secondary developers.

I prefer using Markdown for internal documents. There are several uses of the same. It is easier to make everyone contribute to Technical Documentation when we are using Markdown. The documents created using Markdown don't have any tools dependency. You can use any of the several Markdown tools for authoring and editing markdown documents.

You can author internal documents using Confluence or MS Word, but I prefer Markdown because it will be easier to maintain documentation in the long run. Most Markdown tools give only the essential formatting options and do not allow any custom styles and formatting. It makes it a lot easier to import the Markdown source to other tools.

External documents

The external documents must convey the company's brand image. Marketing manuals, user guides, and datasheets are among the examples of external documents. Use professional authoring tools such as FrameMaker, InDesign, MadCap Flare, or Paligo to author the external documents. Create datasheets and marketing brochures that need high-quality print using InDesign. FrameMaker is ideal for PDF, and it can handle large documents. It is easier to create customized PDFs such as an A5 size booklet using FrameMaker.

A lot of large corporations use custom fonts in external documents to convey their brand image.

Desirable traits in a Technical Writer

Multipotentiality

Technical Writer needs to be a jack of all trades. A good Technical Writer has good language skills, is tech-savvy, works well with people, is conversant with tools and technologies, is a bit artistic in playing with words and designing graphics, and knows some project management. The Technical Writer needs to be able to understand code.  You do not need to be a good coder by yourself, but the ability to reuse the code snippets appropriately and understanding the API calls will help.

The Technical Writer must learn any technology domain or the product domain very quickly and develop a broad overview of products. You are not required to stick to a single product domain. Technical Writing is a domain-independent job though there are some Technical Writers who prefer sticking to one.

Flexibility

If you are a Technical Writer, your schedules go for a toss no matter how hard you try not to allow that. An engineer or any other project stakeholder you want to meet may not be available, and you will have to reschedule meetings. You may not have much to do on a few days, and you have excess workload on a few other days. Sometimes you may have to stretch your day beyond the working hours to catch up with someone in a different geography. Sometimes a deliverable is so urgently needed that you work during the weekend as well.

Learn from everyone

“In my walks, every man I meet is my superior in some way, and in that I learn from him.” ― Ralph Waldo Emerson

A Technical Writer will have to learn from everyone. Being a Technical Writer, I often come across situations in which I had almost nil knowledge of the product and the domain when I joined a product team while most members were product veterans. You need to develop the repo and build trust quickly. There will be releases around the corner, and you will have to prove yourself and impress in a short time. I will not make any distinction between a senior engineer and a junior engineer which I have to learn something from them.

Repo with people

Allow your Technical Writers to decide which process works best for their projects. A Technical Writer needs to establish a good repo with SMEs (Subject Matter Experts), and a mechanical process through JIRA tickets may not help there. The repo builds because of sincerity, commitment, and hard work. There are no shortcut ways for the same. Even the smartest Technical Writer will slog long hours and follow up with people to make them part with the information you need. It takes substantial effort to become a connected Technical Writer who can establish a connection with dozens of people just at the right time and jell with them as if you knew them for a long time.

Convert data into information

The Technical Writer needs to be good at connecting the dots. You have pieces of information, and a lot of it is not clear and complete. You have some of it in JIRA, mails, chats, excel sheets, presentations, wiki pages, meeting recordings, and you just heard some of it in a conversation. Some of the information you need is in somebody's mind, and you need to talk to them to get that information. Piece all this data together and derive information from it. Translate it into words for your readers.

Be good at troubleshooting issues

The ability to troubleshoot issues is one of the essential skills for being an engineer, and it applies in equal measure for Technical Writers. A lot of engineering goes into writing documents. Making things look effortless takes a great deal of effort. I learned in my first job that we apply metadata to information, use information classification, use symbols to draw user attention. A writer needs to know many tools and be able to install, configure, and troubleshoot them. Making writing effective is a tough job. There are scientific reasons for the fonts and colors we use. Documents must help the company in legal compliance. 

Never ignore your wellbeing

I am nearing two decades into my career. To be precise, I started my career towards the end of 2004. I was without a job for close to a year after completing my education, and I was already very desperate. I had a lower-middle-class upbringing and used to be broke nearly always. Getting a job was my first opportunity for redemption. I got the chance to do well, and I tried my best to utilize every ounce of it. I have worked primarily in product companies. I am good at juggling work. You realize over the years that you need to give high priority to your wellbeing. It may not apply in equal measure to everyone, but it applies to everyone like me. Give your best for work, but have as much focus on your wellbeing. Do not get caught in the monotony of work. Spend enough time with yourself and your family. Read a good book at least once in a while. Upgrade your skills and nourish your intellectual side.

Time management

Technical writers need to be good at time management. Be clever enough not to come under pressure. Make a clear distinction between what is the priority and what is not and communicate diplomatically.

Life long learning

Cultivate the habit of lifelong learning. The goalposts change almost every day in our field. Never settle for safety and convenience. Keep pace with the evolving technology. In my observation, expectation from Technical Writers has been on the increase. Nowadays, your job can involve multiple job functions. Technical Writer happens to be a traditional job title, but Information Developer and Technical Communicator could be the more appropriate job description. You sometimes double up as a Language Editor, Information Architect, UX Writer, API Document Writer, Translation Coordinator, Technical Documentation Team Lead or Manager, etc. Having some secondary skills related to product development, testing, and deployment can be an added plus. 

Who the Technical Writer reports into

Who the Technical Writer reports to depends on the organization. Some companies may not have a management structure for Technical Writing. In such as case, Technical Writer may get aligned with engineering, product management, QA, sales and marketing, or technical support. It is preferable to have dedicated management vertical for Technical Writing. Some companies have a Learning Management organization with a Chief Learning Officer at the top of the vertical reporting directly to the CEO, COO, or any other senior executive or Vice President. It will be easier to handle initiatives for Technical Documentation in such a case. The learning vertical will be responsible for training, curriculum development, and technical documentation, along with marketing documentation.

Outsourcing vs. insourcing

The company can choose to outsource Technical Writing for several reasons. It can be for the cost advantage or operational efficiency, but there are some disadvantages with it. Consider the pros and cons carefully before you make the decision. It is better to have an in-house Technical Writer if you expect higher efficiency and technical competency. Outsource the work if it is more routine and repetitive with known and predictable inputs.

Technical Writing vs. Technical Authoring

Technical Author and Illustrator

Technical Authors often work on the heavy engineering side in Aerospace and other domains. They primarily create CMM (Component Maintenance Manuals), Repair Manuals, and other engineering manuals.

Technical Author generally has engineering qualification with Mechanical and related fields. It is desirable to have skills in Adobe Illustrator and CAD tools apart from skills in authoring tools. Often, Technical Publication or Tech Pubs is the for the Technical Authoring department.

Technical Writer

Technical Writers often work in the software domain. It is possible to interoperate between Technical Writer and Technical Authoring, and most companies term both work as Technical Writing. Often, Technical Documentation is the name for the Technical Writing department.

An experienced and skilled Technical Writer may have created the entire portfolio of documents for a product or platform. The experienced Technical Writer may have worked on API guides and other technical guides. The Technical Writer is conversant with technologies and has a natural flair for writing.

Be generous in giving work

It applies to anybody doing any work but applies in great measure to Technical Writers working in a product company. There is almost no limit on the amount of work that you can do. You will be surprised to know that even the best of the product companies have poorly maintained documentation. It is almost impossible to have things totally in order irrespective of your budget and human resources. A Technical Writer who wants to do quality work will always have their hands full. The documents have poor formatting, seriously messed up stylesheet, language issues, and are not optimized for easy search and reusability. You are lagging in innovation, and there are plenty of problems to fix. Fix as many issues as you can. The industry may be going through its worst, and still, the company will have good reasons to have you in the role.

Have a set process for Technical Writing

Many managers believe that they can plugin a Technical Writer into the project when they discover the need for some documents. You can plugin some Test Engineers into a project. You can plugin some developers to develop a feature or module, and the effort can takeoff with one briefing. But the Technical Writer sometimes gets too overwhelmed with the same approach. You had no work for some time, and later you find that all flood gates are open and that you are drowning under the piles of work, and everyone is pinging you. You will have a hard time prioritizing work because everything is urgent.

Try to have a set process for Technical Writing. The item needs to be in your backlog first. The backlog item is estimated, prioritized, and has determined inputs, contacts, deliverables.

Have a blueprint for your deliverables. Ceremonies are important. A formal takeoff with commencement criteria fulfilled will logically lead to the finish line with success. Anything that is void and remains unidentified will give you trouble. The project can have a southward journey when there is a difference between your assumptions and your manager's assumptions, and there is not enough communication to bridge the gap. Technical Writers may feel a high probability of it because they may be reporting to a manager who has no background in Technical Writing. But a formal ceremony or kick-off can help bridge the gap. Discuss the possibilities, the tools to use, the present state of the deliverables, and every other concern during the takeoff. The things that begin will do end well.

Information Architecture

Consider information architecture for your project at its inception. Good information architecture will save the technical writers time and effort. Trying to do it retrospectively after the project grows large will cost a lot of effort and is error-prone. 

Tools to use

Consider the long-term needs of your project while you decide on the tools to use.

Templates to use

Consider the templates to use at the initial stage itself. It can become a sticky issue later if you do not give enough thought to it early on. Get buy-in from the stakeholders for the templates that you want to use for the project.

Think twice before changing the default fonts and styles. Most authoring tools come well packaged, and you do not need to customize too much unless your company is ready to invest in developing custom fonts. Consider how the content renders on a browser and other technical constraints.

Source file archival

Consider ways for safe archival of source files. At times, we used SVN, ClearCase, BitBucket, SharePoint, and others. Now, archiving source files to OneDrive seems to be the best.

Information Type

You can consider the DITA classification of information and Information Mapping to identify the information types.

Folder structure

Folder structure for your project forms a part of the Information Architecture. You can consider a folder structure as in the following:

• WORK - all the work-related files go here, and it is the container for all other work folders.
• CONTENT - document source files go here
• MEDIA - images, graphics, animations, and videos go here
• RESOURCES - code snippets, scripts, stylesheets, and other resources go here
• REFERENCES - reference documents go here
• BACKUP - place here the files for which you want to have backup
• ARCHIVE - place the documents which are no longer in active maintenance here
• PUBLISH - the final published files must go here 

Related articles:

• Planning in a technical documentation project
• Shiny object syndrome in Technical Writing
• Fight the passive voice with zombies
• Build knowledge base
• Do not let yourself be a pushover
• Tool independent technical documentation
• Techniques for cost-effective technical documentation

The ability to learn is the key to survival. We can learn faster by learning from each other.