What is technical writing

It's been five hours that you have spent setting up your WordPress site. But you couldn't move the needle.

Few hours later, tired, you randomly explore the WordPress documentation—your unsung hero.

You checked through their help center, read the FAQs and installation guides. And voila, within the next few hours, you published a basic Wordpress site.

Thanks to the technical documentation on the website. It saved your time and the headache you would have been drowning in otherwise.

Just like WordPress, almost every software has technical documentation written and published on their website. Why? To make their user experience smoother.

In this article, we’ll share everything about technical writing and how you can create your first technical documentation.

Let's get started.

What technical writing really is?

Technical writing is a specialized, user-centric form of writing that simplifies complex, technical topics into easy-to-digest and understandable language.

The goal of technical writing is simple: get readers to follow the instructions.

Think: user manuals, guides to install an app or software, product specifications of technical software, standard operating procedures (SOPs), etc.

For example, if you want to install Microsoft Office into your system but don't have clear instructions on how to do it.

You download the installation guide by Microsoft, which details all the steps needed to install the software on your computer.

It lists all the steps—from downloading the software to running it and following the prompts.

Types of technical writing

Technical writing branches into five different categories you should know about.

• End-user documentation: It educates the user of a product on the core functionality of the product and how to solve common troubleshooting issues. For example, user manuals, installation guides, help centers, FAQs and knowledge base.
• Process documentation writing: This type of technical writing focuses on standardizing procedures within the company and is designed specifically for internal teams. For example, standard operating procedures (SOPs) and internal wikis.
• Technical marketing communication: It leverages technical expertise and marketing strategies together to convey the value of complex products. For example, case studies, landing pages and business emails.
• Expert-to-expert technical writing: It is niche-focused and provides expert-rich information to people who are already experts in their field. The catch? This type of writing can only be written by technical writers or people who have specialized knowledge or are experts in their field. For example, white papers and research summaries.
• Technical reports: This type of writing presents detailed information about research findings, project outcomes, or technical analyses. For example, research reports, progress reports, technical proposals and feasibility reports.

Also read: What is engineering documentation?

Examples of technical writing

But what exactly does technical writing look like? Let's check out a few examples of technical writing to understand it better.

Product documentation

A product documentation provides detailed information on the technical specifications of the product, its features, step-by-step instructions on getting started with the product, and comprehensive manuals on how to use the product.

It usually includes system specifications for users to run the software, installation and usage instructions, FAQs, or a knowledge base.

Agorapulse, for instance, has clean and minimal product documentation on its website.

When you click on the specific block, say ‘getting started’, you'll see the different hyperlinked questions on troubleshooting tips and feature-specific information.

Also read: The documentation system that drives Agorapulse

API documentation

API documentation is a collection of instructions explaining how developers interact with software applications. This documentation provides detailed information about the API’s endpoints, code examples, and authentication methods.

For instance, Kit API documentation includes a brief overview and sections like changes, authentication, OAuth, API Keys and more.

Standard operating procedures (SOPs)

SOPs are like GPS for teams—they provide clear instructions to help team members understand how to accomplish a specific task within a company.

Here's an example of what an employee onboarding SOP looks like:

Release notes

Release notes inform users about new product features, improvements, and bug fixes in software updates.

For example, Wix has published the release notes on their website. Every release note has a date and is structured briefly in bullet points. The best part? Every update is hyperlinked to specific technical documentation instructions.

Principles of technical writing

Now that you know the different variations of technical writing, let's understand the five core principles of technical writing.

Each content type is written based on these principles.

Clarity and precision

When reading technical documentation, readers have one goal: quickly finding and implementing the information.

You can achieve this goal for readers reading the technical documentation only by doing this one thing: writing with clarity and conciseness.

And how to do it?

• Keep your writing clear and to the point.
• Provide definitions for technical terms wherever needed
• Remove jargon from your writing—words that impact the readability such as ‘just’, ‘that’, ‘very’, etc.

Here's an example of poorly written technical documentation.

Image Source

This is how it would look when improved for clarity:

You see the difference? Reading the first documentation makes it hard for the reader to wrap their head around the information.

But the improved version? It simplifies the information and is written in fewer words and in a way that the reader can absorb and implement.

That's precisely how you need to write your documentation for clarity.

Thoroughness

To help readers accomplish their goal—troubleshooting an issue in the app or building the DIY furniture—you need to include every minute detail to help the readers follow the instructions step-by-step.

This means sprinkling the documentation with every bit of detail with diagrams, flowcharts, visuals, code, and videos to simplify the information and make it actionable for the reader.

Like here, Storylane covers every micro step to help the users get started and create their first demo on the platform.

Logical structure

To help the reader take action from point A to B and achieve the desired result, you need to structure your documents well. Think: a series of meaningful sections, headlines, titles, and instructional steps.

Let's understand better with an example.

A user manual starts with a troubleshooting guide, then jumps to installation instructions, followed by a section on features, and ends with glossary terms.

You see the problem? Users will get to read information they don't need at the moment. And the information they needed? That piece of information is buried under advanced topics.

That's why you need to think through it logically and make the documentation user-focused by including the information in logical sequences.

Factual accuracy

Unlike other forms of writing, where one can add personal opinions, anecdotes, and storytelling, technical writing requires facts, knowledge and research.

Technical documentation should focus on facts and explain what a product does, who it is intended for, and what the value proposition is.

For instance, Slack’s documentation doesn't glamourize how they're the best collaboration tool. But, it subtly introduces itself and goes straight into the agenda of the document—how to get started with Slack and the different elements the user will see in action within the tool.

Problem-solving

Every technical documentation should have one destination: to solve the user’s problem.

For this, you need to first identify the problem you're solving with the documentation. Then, write the exact solution that would help them. To explain the solution better, you can also include examples, annotated screenshots and video tutorials.

Slite uses a mix of loom videos and product screenshots when giving specific instructions.

In their ‘How to Set Up your Workspace’ section for instance, you'll see that the document has listed all the features the user needs to be familiar with. For more clarity, a product screenshot is added to make the instructions clearer to implement.

The technical writing process

The big elephant in the room: how to *actually* write a technical documentation? Writing technical documentation goes through different phases: planning, research, writing and editing, and finally publishing it.

Let's understand each phase in detail.

Phase 0: Planning

First, know who you're writing the documentation for—developers, system administrators or users? Now, identify who will use the document and what information they'll seek.

Then, ask yourself:

• What is the #1 goal readers want to achieve after reading this documentation?
• Are you writing for experts or general audiences?
• What information will this documentation cover?

Phase 1: Research

Finally, collect the necessary technical details—product specifications, design documents, existing documentation and insights from subject matter experts.

Create a questionnaire

Describing a new feature of the app? To write about it, the tech writer will need to understand the ins and outs of the product feature.

Some questions that could be excellent starting point include:

• Is this a new feature or an improved version of the older feature?
• What does it do, and how can users use it?
• What topics cross-reference this feature?
• Are there any notes/ warnings to be included in the feature description?
• Do you need screenshots, gifs, diagrams or videos to present the information better?

Identify credible sources

Find the sources with factually accurate and up-to-date information. There are two credible sources that you can use to write your documentation:

Product

If you're writing a feature documentation, try the feature yourself and document the exact step-by-step process.

This way, you get first-hand experience with the product and clearly understand how the product works—right from step 1 to step N—helping you write accurate instructions.

Subject matter experts (SMEs)

Interview the internal SMEs—experts from the product or engineering teams—to extract insights if you're explicitly writing about the product.

This helps you get insights straight from the person who has closely worked on the product, and they'll have rich insights.

Image Source

But the real question for technical writers is, “How do I interview SMEs?”

Simple. Ask the SMEs open-ended questions specific to the information you need. Say you're writing a feature documentation, you could ask questions like:

• Can you demonstrate to me the process of using this feature?
• Do you need elevated permissions during this step?
• How can this process be identified if it fails, and how can it be escalated?

Capture as many insights as you can from the SMEs in one interview. But if needed, follow up with the SMEs on another call and clarify your doubts.

💡Pro tip:

• Use video recording tools to record the SME interview and then use the recording to write your documentation.
• Instead of having all the research scattered on Google Docs, use doc collaboration tools like Slite to organize everything in one place—recorded videos, resource links, etc.

Phase 2: Content organization

Done with the research? Organize all the information in a document and draft the outline.

For this, structure your documentation from the user’s perspective—what’s the first thing they want to read?

Think about it and structure your headings and subheadings accordingly.

For instance, start with the general information and then move to specialized features.

That‘s exactly how Reddit’s API documentation has done it. It covers all the API elements throughout the entire documentation.

The document starts with general information and then branches into specific API features that users can browse for their needs. Each feature contains a description, method, code example and parameters.

Considering how Reddit has written its documentation, you can create an outline with clear headings and subheadings. Here's a sample outline you can use to begin with:

Phase 3: Writing and editing

Now that you have a structured outline, it's time to move to the next step: writing the technical documentation. How to go about it?

Start filling the outline with the information you have gathered during the research process.

Say you're working on the ‘authentication’ section from the sample outline. You'll add all the information you have collected from the SME interview here.

But that's not all to write your technical documentation. Here are a few ways to make it stand out:

• Cover the information step-by-step: Elaborate each step in detail so that the users know how to finish each step and move to the next step without making a mistake while following the instructions.
• Write using concise language: Keep the language straightforward and concise without adding too much technical (and irrelevant) jargon and complex phrases.
• Format for readability: Make sure you break the text into paragraphs, format interlinking, and demonstrate the information well using visual elements such as videos, screenshots and GIFs.

Once you have written your first draft, it’s time to run through the editing checks.

When editing, focus on two types of editing:

Step 1: Developmental editing

Developmental editing aims to make the documentation more effective while evaluating it based on information and relevance to the audience.

So, check the draft for structure and content and evaluate the logical flow of ideas, information relevance, and audience alignment.

Step 2: Line editing

Once you've completed the developmental edits, it's time to refine the sentences.

For this, spot the sentence structure, word choice, narrative coherence and writing voice. Also, focus on the writing style and language to make sure each sentence delivers the information with clarity.

Step 3: Copyediting

Now check the documentation for technical accuracy—spelling errors, punctuation, fact-checking and style guidelines.

Want to speed up your copy editing process? Use tools like Grammarly and Hemmingway.

Phase 4: Review and feedback

Once you have written and edited the document, it's time to ship it to SMEs to get their feedback and make the necessary changes. How?

• Share the draft in a doc collaboration tool like Slite and invite the SMEs to collaborate on the document.
• Ask the SMEs to share their feedback on parameters like expertise, user-specific information that has been missed and the relevance of documentation for the users.
• The SMEs can highlight the parts of the document where they would like to add more insights and add their comments.

Instead of the back and forth of reaching out to the SMEs and getting on a call with them for feedback and clarifying points, this form of collaboration speeds up the feedback process. Win-win for the tech writers and SMEs.

Phase 5: Publishing and maintenance

And here comes the final step after all the hard work—publishing your documentation.

For this last step, choose the right publishing platform to get your documentation live.

Here are five options you can choose from:

• Creating the documentation website
• Publishing the docs on GitHub
• Using a publishing tool
• Sharing via cloud folders
• Launching a help center page on your website

Out of these, using a publishing tool and launching the help center page are the best ways to publish the document.

• If you want to create user documentation, launch the help centre page on your website.
• If you're going to create the documentation for your internal team, using a publishing tool like Slite is the best—it even lets you verify the documentation and keep the information up-to-date.

Tools to speed up your technical writing process

• Documentation platform: Organize your research—all the ideas, materials you've collected, video recordings and transcriptions you've captured—in a centralized hub to access everything in one place. It also simplifies sharing the gathered information with stakeholders and SMEs with which the technical writer collaborates. This tool is perfect for your research, planning, and writing process.

Example: Google Docs, Notion or Slite.

• Collaboration tools: Ditch the back and forth of reaching out to SMEs and waiting for days to get their approval. You can collaborate asynchronously with collaboration tools by messaging the SMEs and stakeholders. This works even better if the documentation tools have in-built collaboration features or integration with collaboration platforms. These tools are perfect when you need feedback on the first draft from SMEs—you can ask them follow-up questions and clarify the doubts without leaving the documentation.

Example: Slite and Slack.

• Editing tool: Drafted your first technical content piece? Use editing tools to speed up your editing process during the line editing and copyediting stage. With such editing tools, you can edit your content for spelling errors, punctuation, sentence rephrasing and clarity.

Example: Grammarly, Hemmingway Editor or Wordtune.

• Design tool: Once the content has been approved, the next step is to design the visuals. With design tools, you can create all the visuals you want to include in your documentation—infographics, flowcharts and GIFs. These tools also have pre-made templates that you can use instead of designing everything from scratch.

Example: Canva for designing and Zight for screenshotting and annotating the product screens.

• Video recording and transcription tool: During the research process, when gathering insights from SMEs, video recording and transcription tools are your saviour. Integrate these tools during the call; it will record the call for you and even provide a transcription of the entire call. This way, tech writers can focus on listening to the SME's insights without being distracted.

Example: Zoom, Fireflies.ai or Fathom.

• Publishing tool: This is your hero tool for publishing and maintaining the content, especially if you’re not publishing the technical content on your website. With these tools, you can publish content and embed different formatting styles—tables, databases, and content straight from other tools. Most importantly, you'll be able to keep your content fresh and up-to-date without doing it manually.

Example: Slite and Notion.

Best practices to write your first technical documentation

All set to write your first technical documentation? Here are a few best practices you must remember:

1. Style guides

Use a style guide to improve your technical documents' writing and formatting standards. If you have never created a style guide before, consider these components:

• Tone and voice: Define the tone and voice your audience resonates with—formal, informal or neutral.
• Grammar and punctuation: Provide rules that should be strictly used and specify the use of punctuations like hyphens, em dashes, semicolons, the Oxford comma and periods (to include or not) in bullet and numbered lists, and capitalization.
• Formatting guidelines: Mention the details on fonts, use bullet lists or numbered lists (or both), and use emojis and formatting styles—bold, italics and underline.
• Terminology and abbreviations: Provide guidelines on how to use the terminologies. Should the acronym be mentioned at the end of terminology only when introduced the first time, or should it be mentioned every time it is mentioned in the document?
• Visual elements: Highlight the rules for using visuals in the document. Can the documentation include flowcharts? Or does it have to be specifically product screenshots and tutorials? When adding alt-text and captions to the images, is there a specific way you need to write them?

For instance, Microsoft's writing style guide is packed with useful examples, including what works and what doesn't work.

You'll see the tables labelled with headers like ‘Use this' and ‘Not this’ to provide clear instructions, making the information easy for readers to grasp at once. Also, it clearly mentions the scenarios where the technical writer needs to skip periods, including the Oxford Comma and not include spaces around em dashes.

1. Documentation templates

Instead of writing the content from scratch—without a directional structure—use pre-made documentation templates.

You’ll not be working on a blank canvas. With these templates, you know the exact sections your documentation will include—it saves you time and gives clarity on the research you need to conduct and insights you need to extract from SMEs.

Here’s an example of a pre-made documentation template:

Inside the template, you get the different sections that your document should include and details that you can include based on your research.

1. Content Structure

Organize your documentation with clear headlines, lists, and visuals such as screenshots, flowcharts, and video tutorials to help readers digest the information quickly and in a simplified manner.

Take a peek at Reply.io’s API documentation.

Each section is spaced out with different headings, numbered lists and bullet lists. To emphasize a few words, they have formatted them in bold and made minimal use of emojis. Plus, the documentation looks clean, with the white space added after each section.

1. Writing convention

Instead of overcomplicated, fancy language, use simple, plain language to make it easy for readers to understand the complex, technical information.

Focus on using active voice and only 10% of passive voice. Also, make sure your sentences are concise and fluff-free, bringing clarity to your documentation and simplifying the understanding of the information.

💡Pro tip: Check your readability score on Hemmingway—it should be grade 9 or less.

1. Quality assurance

Before publishing the content, get the SMEs to review the content for accuracy and usability. Once the content is published, conduct regular checks to keep the content up-to-date.

For instance, the internal documentation and SOPs your team has been using use Slite’s doc verification feature to request the SMEs to verify the document. Once the document is verified, all the team members know that the documentation is accurate and ready to be used.

Write your first documentation with Slite

Let's be honest: conducting the research, collaborating with SMEs, getting feedback and maintaining the published documentation. It’s a lot of hard work.

It increases the friction in the content creation process. That's where you need documentation tools like Slite become the night in the shining armour.

With Slite, you can:

Step 1: Capture your research—links to other documentation for reference, video tutorials or screenshots you'd include in your content or the SME video recording, and organize it within your Slack channel.

Step 2: Invite the SMEs to the workspace. They can add comments to the research document and give their feedback, and even additional resources for the technical writers.

Step 3: Write your first documentation within Slite or integrate the tool with Google Docs, if that's where they have written the draft. SMEs can review the document and add comments, and tag the writers to share feedback.

Step 4: Request the SMEs and stakeholders to verify the document to make sure the documentation is accurate and up-to-date. You can do this before publishing the document or even after the documentation has been published.

Want to see how Slite can boost your team’s collaboration during the technical content creation process? Try Slite for free.