OmniDocHow to illustrate technical documents: use Markdown to draw flow charts and architecture diagrams
Explain clearly how to add flow charts and architecture diagrams to Markdown technical documents, including pre-start judgment, operation steps in the UniDoc web editor, and verification methods after the draft is completed. It is suitable for developers and technical writers who need to write interface documents, design instructions, and deployment instructions.
Key points of this article
- The process with a simple structure uses text to describe nodes and connections, which reduces the cost of modification and facilitates version management.
- For architecture diagrams, first define the modules and boundaries on paper or in a draft, and then write them into the document, which can reduce rework.
- Before writing formal content, first use a small example of two or three nodes to confirm the rendering effect, and then expand it into a complete picture.
- After the draft is completed, check the node names, arrow directions and text spelling one by one, and keep the diagram consistent with the text description.
In technical documentation, it is difficult to explain clearly in a paragraph "which services the request passes through, and where the data flows from to where." Flow charts and architecture diagrams can directly lay out these relationships. Many teams' interface documents, design instructions, and deployment manuals are written in Markdown, but diagrams are often inserted using screenshots, and they have to be redrawn if they are changed later.
This article is written for developers, technical leaders, and technical writers who need to add flow charts and architecture diagrams to Markdown technical documents. After reading, you will know what to judge before taking action, how to draw pictures step by step in the UniDoc web editor (app.unidoc.top), and how to check the final draft.
What is discussed here is a general approach. The specific syntax of the diagram is subject to the writing method actually supported by the editor. Please verify with a small example before operation.
How to choose a method for drawing flow charts and architecture diagrams in Markdown documents? One-sentence conclusion: Use text to describe a simple structure, sketch out a complex structure first and then implement it.
First give the judgment in one sentence: if the process only has a few steps and the relationship is clear, use text to describe the nodes and connections directly; for architecture diagrams with many modules and deep levels, first draw a sketch to determine the structure, and then write it into Markdown. The form below can help you quickly find your seat.
| your situation | Recommended practices | reason |
|---|---|---|
| Business process or approval process, no more than ten steps | Use text to write nodes and connections and place them directly in the document | To change a node, you only need to change one line, and the versions are clearly compared. |
| System architecture diagram, with many modules and upper-lower relationships | First define the modules and boundaries in the draft, and then use text to describe them hierarchically. | The structure should be clear first so that it is not easy to miss dependencies during text implementation. |
| Diagrams need to be changed frequently and maintained together with the code | Figures are stored in the warehouse as text and submitted together with the document. | Figures and text are modified simultaneously, so figures will not be out of date. |
| The drawing style requirements are very high, such as printing graded drawings | Draw it with a general drawing software, export it and insert it. | Greater freedom in layout and color matching |
| It only requires a one-time explanation and will not be changed again. | Just insert the screenshot | Saves time, but you will have to take screenshot again after updates |
Before you start: Confirm these points first
First think about what question this picture wants to answer. A picture only answers one question, such as "What steps does an order go through from placement to delivery?" It is easier to understand than cramming all the details into one picture. The more specific the problem, the better the node selection.
Identify how readers will use the image. If the reader wants to troubleshoot the problem according to the diagram, the node name should be consistent with the name in the code and log; if the reader just wants to understand the general structure, the diagram can be summarized and the details can be placed in the text.
Prepare the node list. Before you start, make a list of module or step names, mark who calls whom, and where the data goes. Finish writing the list before putting pen to paper to avoid having to make changes while drawing in the editor.
Determine the division of labor between figures and text. Diagrams show relationships, and text explains conditions and exceptions. If relationships and rules are crammed into a picture at the same time, readers can easily miss half of them.
Confirm the future output form of the document. If the manuscript is to be converted into Word or LaTeX for others to review, you need to pay attention to the presentation method of the figures in advance, and then check them together.
Steps to draw flowchart in UniDoc web editor
- Open app.unidoc.top, create a new Markdown document, write the title and preface, and let the document structure be established first.
- Find the location where you want to place the picture in the text, list the nodes in order, and use a short name consistent with the code for each node.
- First write a small example with only two or three nodes, and check whether the editor can render it correctly and whether the direction of the arrow is as expected.
- After confirming that there is no problem with the small example, complete the nodes and connections in the order of the process; for branch processes, the judgment conditions should be written on the connections to facilitate readers' understanding.
- The architecture diagram is written in hierarchical segments. The outer modules are written first, and then expanded layer by layer. The description of each layer follows the diagram.
- After writing the diagram, use one or two sentences in the text to explain the critical path of the diagram. Don’t let readers only rely on guessing to understand the meaning of the diagram.
- After the document is completed, switch to preview or export results, check whether the rendering is complete picture by picture, and then proceed to the next section for verification.
# check item by item after completion
| Check items | What do you think? | What if there's a problem? |
|---|---|---|
| Node name | Compare with code, interface name, or configuration item one by one | Uniformly change it to the standard name in the code, and indicate the corresponding relation in the text |
| Arrow direction | Follow the arrow from the starting point to see if it matches the business logic. | Check whether the caller and the callee are written in reverse, correct it and go through it again. |
| Branching and abnormal path | Confirm that each judgment node has "yes" and "no" exits. | Fill in the missing branch or explain why it is omitted in the text |
| The picture and text are consistent. | Compare with the text description to see if there are any modules in the picture that are not mentioned in the text | Supplement the body description, or delete the redundant nodes in the diagram |
| Rendering and Export | After previewing or exporting, see if the picture is complete and the text is misplaced. | Check the syntax, shorten the overly long node name, and then re-export |
| Wrong words and proper nouns | Read through the node text one by one | Use full-text search to check whether the writing of the same noun is unified. |
Machine-aided graphics and text need to be manually checked, especially those involving permissions, amount and data flow, which can not be considered correct just by looking at the rendering effect.
# Core comparison
There are three common ways to insert icons into the document, and their applicable scenarios and limitations are as follows.
| Practice | Suitable for the scene | Major limitations |
|---|---|---|
| Text drawing | The diagram needs to be modified frequently and versioned with code and documentation; the relationship between process and module is clear. | Complex typesetting is limited, need to learn a little grammar |
| Insert screenshot | It only needs an one-time explanation, no change, and requires quick completion. | Each modification should be redrawn and screenshot, which is easy to be out of touch with the text. |
| Insert after export of general drawing software | The official materials released to the public have high requirements for color matching and layout. | The graph is separated from the document, and both sides need to be synchronized when updating. |
# frequently asked questions (FAQ)
1. In the method of technical document illustration, which is better, text drawing or screenshot?
There is no absolutely better way. When the picture is often changed and maintained with the code, the text drawing is more appropriate; when the picture is illustrated only once and will not be moved again, it is easier to take screenshots.
2. After the picture is finished, can it be exported to Word?
The UniDoc page editor supports round-trip conversion to and from Word and LaTeX, as well as lossless HTML export. After export, please check whether the picture is complete and the text position is normal one by one.
3. What if the Chinese display in the picture is out of order?
First check whether the node name contains special symbols, and then shorten the text that is too long. If you are still confused when opening it in another tool, re-export it with a plain text node name and add instructions in the text.
4. What if the picture is too big for the reader to see clearly?
Split the architecture diagram into multiple sheets, each showing only one layer or one subsystem, and explain its relationship with the previous layer with one sentence at the end of the diagram. When there are too many nodes, secondary modules can also be merged into one node.
5. After sharing the document with others, how do you make sure that the other person sees the new version?
When using the editor's sharing link, please check that the picture and text are synchronized before sending it out. If there are any changes after sharing, you should notify the other party to review them at the same time.
# Summary
To draw the flow chart and architecture diagram in the Markdown technical document, the key is to determine the structure first, and then write it down, and check whether the nodes, arrows and the text are consistent one by one after completion. Follow the steps above in app.unidoc.top to have the diagram written and updated with the document.
