Skip to main content

Technical Writer Tutorial


Welcome! Technical writing is the crucial link between complex code and a thriving developer community. It’s the art of turning brilliant engineering into an easy-to-use product.

For CodeHarborHub, our goal is to produce documentation that is not just correct, but a genuine pleasure to read. This tutorial will guide you through the principles of effective technical communication and the specific tools our platform provides (like Live Code and Mermaid) to make your content exceptional.

Chapter 1: Know Your Audience and Purpose​

Before you start writing, answer these two questions: Who is reading this? and What do I want them to be able to do?

1.1 Define Your Reader (The Persona)​

The language, detail, and assumed knowledge must match your reader. Tailor your content!

Audience TypeKey GoalTone & Focus
Beginner/Learner"Help me build something simple and feel successful."Use friendly, encouraging tone. Focus on Tutorials and step-by-step guides. Define all technical terms.
Experienced Developer"I need the precise syntax and edge case details."Use a professional, concise tone. Focus on Reference and in-depth Conceptual docs. Assume basic language knowledge.
Architect/Manager"I need the high-level overview and trade-offs."Focus on Conceptual overviews, system diagrams (using Mermaid!), and integration guides.

1.2 The Four Pillars of Documentation​

Every piece of documentation fits into one of these categories. Structure your writing based on its primary purpose.

PillarGoalAnalogyCodeHarborHub Example
TutorialsLearning (Get started)The cooking class"Your First Component with React"
How-to GuidesSolving (Complete a task)The recipe book"How to Configure OAuth in Your Project"
ReferenceInformation (Look up detail)The dictionary/encyclopediaAPI documentation, function parameters.
ConceptualUnderstanding (Gain insight)The textbook"Understanding Asynchronous Programming"

Chapter 2: The CodeHarborHub Toolkit​

We use MDX, which gives us superpowers beyond standard Markdown. Use these features to make your documentation clear, functional, and engaging.

2.1 Rich Code and Interactivity​

Plain code blocks are good, but interactive ones are great.

  • Interactive Code Editor (live): When showing frontend code (React, etc.), use the live prop to allow readers to modify and run the code right on the page.

    Example Live Code Block
    ```jsx live
    // Let the reader play with the code!
    function Counter() {
      const [count, setCount] = useState(0);
      return (
        <button onClick={() => setCount(count + 1)}>
          Clicked {count} times
        </button>
      );
    }
    ```

  • Multi-language Support (<Tabs>): For tutorials that span multiple languages (e.g., frontend/backend, or different language implementations of an algorithm), use the <Tabs> component.

    Showing Multiple Languages
    <Tabs>
    <TabItem value="py" label="Python">
    ```py
    print("Hello from Python")
    ```
    </TabItem>
    <TabItem value="go" label="Go">
    ```go
    fmt.Println("Hello from Go")
    ```
    </TabItem>
    </Tabs>

  • Code Highlighting: Use a metadata string to draw attention to specific lines of code. This is non-negotiable for complicated examples.

    Highlighting Key Lines
    ```javascript {4, 7-8} showLineNumbers
    function calculate(x) {
      // Line 1 is fine
      let result = 0;
      if (x > 10) { // Highlighted
        result = x * 2;
      } else {
        // These lines are also highlighted
        result = x + 5;
      }
      return result;
    }
    ```

2.2 Visual and Flow Elements​

Use these elements to simplify complex concepts and processes.

  • Diagrams with Mermaid: A picture is worth a thousand lines of code. Use Mermaid for flowcharts, sequence diagrams, and state diagrams. This is vital for Conceptual docs.

    Mermaid for Architecture Flow
    ```mermaid
    graph LR
        User[Browser] --> API(REST API);
        API --> DB[(Database)];
    ```

  • Math Equations with KaTeX: For advanced topics like Data Science, Cryptography, or Algorithm Analysis, use KaTeX for perfectly rendered math. Don't use blurry images for equations!

    Example Inline Equation
    The Big O complexity is $O(n \log n)$.
    Example Block Equation
    $$
    E = mc^2
    $$

2.3 Effective Use of Admonitions​

Admonitions (Notes, Warnings, Dangers, etc.) are crucial for guiding the reader's attention. Use them sparingly—if everything is important, nothing is.

AdmonitionPurposeExample
:::tipBest practice, efficiency gain.Tip: Use asynchronous calls for better performance.
:::cautionSomething that might be confusing or lead to a small error.Caution: The credentials might expire after 30 minutes.
:::warningPotential data loss or breaking change.Warning: This operation is destructive and cannot be undone.
:::dangerSevere risk, security issue, or major system failure.Danger: Exposing this key publicly will compromise all user data.

Chapter 3: Writing with Clarity and Conciseness​

Clear code is good; clear writing about code is essential. The primary goal of a technical writer is to minimize the time a developer spends searching for or trying to understand information. We achieve this through unwavering clarity and aggressive conciseness.

If your documentation is an obstacle course, developers will jump off and find a better path (or, worse, try to figure it out themselves).

3.1 Focus on Action: Use Active Voice​

The single most effective technique for clear technical writing is to use the Active Voice. It tells the reader who (the actor) is doing what (the action) to whom/what (the target). This structure is direct, unambiguous, and shorter.

3.1.1 The Rule of Thumb: Actor-Action-Target​

VoiceStructureExampleImpact
PassiveTarget →\rightarrow Action →\rightarrow ActorThe component was rendered by the React engine.Vague, less direct. Who cares about the engine right now?
ActiveActor →\rightarrow Action →\rightarrow TargetThe React engine renders the component.Clear, immediate, and concise.

3.1.2 Imperative Active Voice (For Instructions)​

When writing step-by-step instructions (the majority of tutorials and how-to guides), use the imperative voice. The "actor" is the implied user ("you"). This cuts out unnecessary words and turns passive observation into direct action.

Passive/WordyActive (Imperative)
The configuration file should be opened before proceeding.Open the configuration file.
The button must be clicked by the user to start the process.Click the button to start the process.
It is recommended that a new branch be created.Create a new branch.

3.2 Eliminate the Fluff: Conciseness​

Conciseness is not about less information; it's about more density. Every word must earn its place on the page. Cut anything that doesn't add meaning.

3.2.1 Remove Wordy Phrases​

Replace long prepositional phrases and bureaucratic filler with single, strong words.

Wordy PhraseConcise Replacement
due to the fact thatbecause, since
at this point in timenow
in the event thatif
a majority ofmost
utilizes / makes use ofuses
with the exception ofexcept
for the purpose offor, to

Example:

  • Wordy: Due to the fact that the API utilizes OAuth, the token must be generated for the purpose of authentication.
  • Concise: Because the API uses OAuth, the token must be generated to authenticate.

3.3 Ditch the Throat-Clearing​

Avoid phrases that simply introduce a sentence without adding value. Get straight to the point.

Throat-ClearingConcise Start
It is important to note that...(Just state the note.)
It should be remembered that...(Just state the fact.)
There are three ways to...Three ways to...
In order to...To...

3.4 Attack Weak Verbs​

Replace weak verb phrases (often involving forms of to be, to have, or to make) with strong, active verbs.

Weak Verb PhraseStrong Verb
is responsible for the migrationmigrates
make an adjustment to the settingsadjust the settings
provides functionality for logginglogs
had a major impact on performanceimpacted performance significantly

3.5 Mind the Gap: Jargon and Acronyms​

Jargon is not bad; unnecessary or undefined jargon is bad. Know the line between useful shorthand for your audience (e.g., "HTTP request") and exclusionary fluff (e.g., "synergistic paradigm shifts").

3.5.1. Define or Replace Technical Jargon​

If a term is fundamental to the topic but might be new to a reader (especially in an introductory tutorial):

  1. Define it on first use.
  2. Use the defined term consistently thereafter.
  3. If the document is for a very broad audience, try to replace it with a simpler, everyday phrase.
Jargon to ReconsiderSimpler Alternative (if appropriate)
Mutate the arrayChange the array
Idempotent operationAn operation that can run repeatedly with the same result
Time to Market (TTM)Release time

3.5.2. Handle Acronyms Gracefully​

Never assume a reader knows your acronyms, especially proprietary ones.

  • Rule: Spell out the acronym on its first use in every document.
  • Correct: The CodeHarborHub Documentation System (CHHDS) provides MDX features. The CHHDS allows for live code.

Chapter 4: Structuring Developer Documentation​

Ah, the "how-to-find-the-thing" chapter! Good developer documentation is a well-organized library, not a disorganized heap of brilliant-but-random notes. The most widely adopted and effective framework for this is the Diátaxis framework.

It structures all technical content into four distinct categories, based on the user's need:

Documentation TypeUser GoalDescriptionAnalogy
1. TutorialsLearning (skill acquisition)A guided, step-by-step lesson for a beginner. The goal is a successful, reproducible outcome to build competence.A cooking class.
2. How-To GuidesDoing (application of skill)Goal-oriented instructions to solve a specific problem or achieve a concrete goal. Assumes some prior knowledge.A recipe.
3. ExplanationsUnderstanding (knowledge acquisition)Conceptual, background, or architectural content that provides context and answers the "Why?"A scientific paper or technical discussion.
4. ReferenceInformation (knowledge application)Technical descriptions of the product's "machinery" (APIs, commands, classes, configuration). Structured for quick lookup.A dictionary or encyclopedia.

4.1 Key Structuring Principles​

  • Separate Content by Purpose: The core principle of Diátaxis. Don't mix a conceptual explanation into a step-by-step tutorial. If you find yourself doing that, you probably need a link to a separate 'Explanation' page.
  • Action vs. Knowledge:
    • Action-oriented documentation (Tutorials and How-To Guides) shows the user what to do.
    • Knowledge-oriented documentation (Explanations and Reference) tells the user what to know.
  • Study vs. Work:
    • Tutorials and Explanations support the user's study (learning).
    • How-To Guides and Reference support the user's work (getting things done).

By clearly separating these four types, you make the content easier to find, easier to write, and ensure a better experience for both a brand new user and a seasoned veteran looking for one specific parameter.

Now that you have the basics, dive deeper into these resources to refine your technical writing skills: