How to write technical documents: writing tools and software selection

Key points of this article

Determine the readers, update frequency and delivery format first, and then choose the tools. The order cannot be reversed.
If multiple people are required to make changes online, the other party needs a Word file, and the document is updated with the code, the three situations correspond to three types of tools.
Use LaTeX for scientific manuscripts with many formulas, and Markdown for structured text. If you need Word-compatible editing, choose an editor that supports Word round-trip.
The writing process consists of five steps: outline, text, charts, review, and export, which saves rework than choosing software first.
Check the title level, figure number, terminology and export format before delivery. Important figures should be compared with the original data.

Many people want to write technical documents for the first time, such as interface descriptions, deployment manuals, product usage guides or internal solutions, but they often struggle with what software to use. In fact, tools are only the last step. If you first think about who the document is for, whether it needs to be changed in the future, and what format the other party wants, the range of choices will be much narrower.

This article talks about the workflow of writing technical documents and how to select writing tools according to scenarios. It does not cover the automatic generation of API documents from code in software development. After reading, you can decide which type of tool you should use, and follow a set of fixed steps from outline writing to delivery.

How to write technical documents? One sentence conclusion

Direct conclusion: first answer "who reads it, how to modify it, whether formulas and diagrams are needed", and then choose the format and tools. If you want multiple people to edit online and the other party wants a Word file, choose a tool that supports Word-compatible editing; if the document follows the code, choose Markdown; if the scientific manuscript has many formulas, choose LaTeX.

your situation	Recommended practices	reason
The team's internal manual requires multiple people to modify it online	Online collaborative editor to share links	Changes are visible immediately, no need to send back attachments
The other party explicitly asked for a Word document	UniDoc web editor (Word compatible editing) or desktop office software	The format is consistent with the other party, reducing typesetting rework.
Documentation is updated along with the code repository	Markdown plain text, with version management	Every change is traceable and the differences are clear at a glance
Scientific and engineering manuscripts with a large number of formulas and cross-references	LaTeX source files, UniDoc supports LaTeX round-trip	Formulas and numbers are managed uniformly by the typesetting system
Read-only finished product, requires fixed layout	Export to PDF or HTML after finalization	The layout is stable when published and is not affected by the reading device

Before you start: Confirm these points first

Who is the reader? If newbies want to read it, they should write more background and terminology explanations; if experts want to read it, they can streamline the steps and focus on parameters and boundary conditions.
Update frequency. For documents delivered once, the concern is the format; for documents maintained for a long time, the concern is historical versions and who has changed what. The latter should give priority to plain text plus version management.
Collaboration method. Who writes, who reviews, how to withdraw review comments, and decide whether the tool should support multi-person editing and sharing. When only one person writes, this has little impact.
Delivery format. Whether the other party wants Word, PDF or web page, you need to ask clearly first, and then recommend the tool. Changing the format midway is prone to problems. Tables and numbers are often misplaced during conversion.
Proportions of diagrams and formulas. If you have many diagrams and need flow charts and architecture diagrams, choose an editor that can draw pictures directly; if you have many formulas, choose a tool that natively supports formulas and export. These two types of requirements often appear together in the same document.

Steps to write technical documents in UniDoc web editor

The following process takes UniDoc web editor (app.unidoc.top) as an example. It supports Word-compatible editing, formulas, Markdown with illustrations, Word and LaTeX round-trip, and lossless HTML export and sharing links, which can cover most scenarios in the table above.

Write an outline first. List chapters in the document using a heading hierarchy. First-level headings correspond to large modules, and second-level headings correspond to specific issues. Once the outline is finalized, the following content will not deviate.
Select the editing method. If you want to submit it to Word, use a Word-compatible editing method; if you are accustomed to Markdown, just use Markdown syntax to write the text directly. Don't mix two sets of markup in the same document.
Fill in the main text. In each section, write the conclusion first, then the steps and examples. Only talk about one thing in a paragraph, and keep the paragraphs to two to four sentences to make it easier for readers to scan.
Insert formulas and codes. Use the formula editing function to enter formulas, do not use screenshots instead. The code blocks are divided into separate sections, and the operating environment and version number are indicated to facilitate readers to reproduce.
Supplementary illustration. Use diagrams to express processes and structures. Write a description below the diagram to indicate what the diagram is trying to illustrate. Figure numbers should correspond to citations in the text.
Share for review. Generate a sharing link and send it to reviewers, so that comments can be processed in one place to prevent the same paragraph from being revised in multiple versions.
Export delivery. Export Word, LaTeX or HTML according to the previously determined format, open the export result and check page by page before sending it to the reader.

Check each item after completion

Before delivery, it is recommended to go through the following checklist. Most rework comes from missing these items.

Check items	How to see	What to do if there is a problem
Title level	In the table of contents or navigation, are the chapters arranged according to the outline and are there any level skips?	Change the skipped title to an adjacent level and recheck the table of contents
Charts and numbers	Whether each chart and table is numbered, and whether the main text references point to the correct numbering	Rearrange the numbers uniformly in the order they appear, and update the citations in the main text
Formulas and symbols	Check whether the formula is complete in the export file, and whether the subscripts and Greek letters are correct	Fix and re-export in the source file; don't just modify the exported file
Terminology consistency	Whether the same concept uses the same name throughout the text	Create a glossary, use search and replace uniformly, and manually review it
Numbers and parameters	Check whether the version number, port, threshold, etc. match the original data	Go back to the original source and compare each item item carefully; don't relying on memory to make changes
Directing the publication format	Check if tables overflow from pages, and if code blocks are lined up or messed up	Adjust table column widths or split long tables; manually insert lines when code lines are too long

If the document contains content recognized by machine translation or OCR, it should be checked paragraph by paragraph, as these are prone to missing characters and mistranslations.

📊 Core Comparison

Format	Specializes in this	The cost
Word-compatible documents	Integrate with office processes, making it easier for others to accept, and the habits of annotation and revision are mature	Weak version management, inconvenient for plain text collaboration
Markdown	The structure is clear, suitable for code repository, and changes can be compared by difference	Complex layouts and limited page layout control
LaTeX	Formulas, cross-references, and references are precisely formatted, making it suitable for science and engineering manuscripts	The learning threshold is high; modifying formats requires understanding grammar

A document often uses two formats. For example, the main text is written in Markdown and exported to Word for the client; Or write the paper in LaTeX, while keeping a copy of the Word version for collaborators to review. At this point, clarify which version is the source file, and only modify content within the source file.

❓ Frequently Asked Questions (FAQ)

1. How can you use a document so readers can quickly find the content they need?

At the beginning, place a paragraph on the applicable scope and reading order, listing the prerequisite knowledge readers need. The table of contents should be navigable, and chapter titles should be specific questions, such as "How to Roll Back Deployment," which is easier to find than "Other Notes."

2. If you only want to write a document, which tool should you choose?

First, let's look at the delivery format. If the other party wants Word, use a Word-compatible editor; If you want to put documents into the code repository, use Markdown; If there are many formulas, use LaTeX. When writing only one copy, don't expect a comprehensive format; sufficient and smooth delivery are what matter.

3. Can Markdown content be converted to Word?

Yes, but after conversion, check the title style, table, and code blocks. Complex tables and multi-page formulas are prone to deformation. After exporting, you need to review each page before deciding whether manual adjustments are needed.

4. What metrics should you look for when choosing a free document writing tool?

Pay attention to four key points: whether there are restrictions on file size and page count, whether the export results have watermarks, how the document content and privacy are saved, and whether the formatting after export is retained. These four items can be verified during trial testing and are more reliable than just looking at advertisements.

📝 Summary

How to write technical documentation? The key is to first identify the readers, update method, and delivery format, then choose the right tool. Proceed in the order of outline, main text, charts, review, and export, and use a checklist before delivery to significantly reduce rework.

Open OmniDoc to edit and export documents online