Technical Writing: The Draft.dev Technical Blogging Style Guide

這是 Claude 翻譯的 The Draft.dev Technical Blogging Style Guide，會寫這篇文章是因為 Hugo 文檔實在是太爛了因此才有動機研究「怎麼寫好文檔」。

以下開始翻譯。

來源：draft.dev/learn/styleguide

摘要： 技術部落格風格指南能確保內容規模擴大時仍維持一致性：

• 語氣指引：使用第二人稱、口語化的表達方式，避免高高在上的用語
• 內容標準：強而有力的開頭與結尾、有憑有據的論點、正確引用來源
• 格式規範：Markdown 格式、正確的標題層級、程式碼區塊、圖片處理方式
• 溝通準則：延遲時主動更新進度、及時回覆郵件

這對於技術內容代理商與工程部落格在規模化維持品質時相當重要。

隨著部落格成長，並邀請更多作者加入撰稿，您需要建立文件與流程，協助維持高品質與一致的風格。為達成這個目標，應建立一份風格指南，讓作者與編輯有共同依循的標準。

什麼是技術部落格風格指南？

一般來說，風格指南會列出對投稿者的期望。依照您重視的重點不同，內容可能比 Draft.dev 的版本更多或更少，但這份指南應能提供一個不錯的起點。Draft.dev 會將此指南發給所有新投稿者，確保他們了解相關期望，並在整個編輯過程中持續參照這份指南。

當然，這並非唯一的技術寫作風格指南範例。如果想比較不同選項，也可以參考 Google 的開發者文件風格指南、DigitalOcean 的技術寫作準則，以及其他相關指南。若您正在建立自己的風格指南，建議多參閱幾份，再決定要納入哪些內容。

Draft.dev 技術部落格風格指南

Draft.dev 專門為想要接觸軟體工程師的公司製作技術部落格內容。雖然大多數作者本身就是軟體工程師，寫作只是其次，但仍要求他們針對每一位客戶遵循一致的標準。

以下風格指南分為四大部分。

技術內容應該如何撰寫？

使用第二人稱

直接用「你」或「您」稱呼讀者，避免使用「我們」。

好的寫法：

您可以使用瀏覽器（如 Chrome、Safari 或 Edge）連上網路上的網站。

不好的寫法：

我們可以使用我們的瀏覽器（如 Chrome、Safari 或 Edge）連上網路上的網站。

使用口語化但不失專業的語言

大聲朗讀您的文章，問自己：「我在工作場合會這樣說話嗎？」可以運用您的實際經驗，但盡量避免使用術語。

好的寫法會用平實的語言直接說明重點；不好的寫法則充斥著艱澀難懂、故弄玄虛的學術腔調，讓讀者難以理解真正想表達的內容。

不要重複自己說過的話

刪去冗詞贅句。就像寫程式時不該重複邏輯一樣，寫作時也不該重複表達相同的意思。

好的寫法會用一兩句話直接點出重點；不好的寫法則會用大量迂迴、重複的措辭來表達同一件簡單的事，例如針對「該用 tab 還是空格縮排」這種常見的工程師話題爭論不休、拖泥帶水地鋪陳。

避免技術寫作中的高高在上語氣

寫作對象是來自不同背景、種族、文化與經驗程度的全球開發者。因此，應避免帶有排他性或「知識門檻優越感」的用語。

好的寫法：

從 main 分支建立分叉，並進行對應的修改。

不好的寫法：

顯然，你只需要先從 master 分支建立分叉，再進行對應的修改。

可以參考 OpenGates 檢查清單，確保您的寫作方式不會將他人排除在外。

技術部落格應遵循哪些內容標準？

如何撰寫有效的技術文章開頭？

每篇文章都應該有一到三段的引言。好的引言需要立刻回答幾個問題：

• 我要處理的痛點是什麼？如何吸引讀者？
• 這個問題的解決方案是什麼？
• 我在這篇文章中要做什麼？

引言的結尾應該讓讀者知道，您接下來會如何教他們解決這個痛點。

技術寫作中應如何支持自己的論點？

對於每一個論點，都要問自己：「我要怎麼證明這一點？」可以透過以下方式：

• 附上可信文章的連結
• 引用其他來源的說法
• 引用學術研究
• 連結到官方文件
• 訪問相關領域的專業人士

好的寫法會附上具體來源的連結來支持論點；不好的寫法則只憑猜測或個人印象，缺乏根據地陳述。

引用與著作權的規則為何？

直接複製自其他來源的文字內容，必須妥善加上引號並標明出處。僅更換句子中的幾個字，並不足以構成原創內容，務必以自己的話重新表達。

不好的寫法會把別人的觀點改寫成像是自己說的話，卻沒有標明出處；好的寫法則會清楚加上引號，並標註原作者，例如引用比爾．蓋茲關於以程式碼行數衡量開發進度的知名說法時，需完整加上引號並註明出處。

圖片使用的標準更為嚴格。除非對方明確授權，否則不可使用其他網站的圖片。如需圖庫圖片，可使用 Unsplash 等網站，或參考其他免費圖庫資源。

如何寫出有力的技術文章結尾？

每篇文章都應包含一到兩段的結論，重申文章的核心論點，並提醒讀者學到了什麼，也可以附上其他延伸閱讀資源。

好的結尾會簡要回顧文章重點，並鼓勵讀者實際嘗試應用所學的技術。

技術部落格採用哪些格式規範？

為什麼技術內容要用 Markdown 撰寫？

所有文章都應以 Markdown 撰寫，並提交至接案時收到的 Google 文件中。

截圖與圖表該如何處理？

如果需要在截圖上圈選或加註文字，請提供已標註的截圖，同時附上未標註的原始版本，方便客戶依照自己的品牌風格重新設計。

若尚無特定偏好，建議可使用以下工具：

• dbdiagram.io
• Excalidraw
• Google 繪圖
• Mermaid-JS
• Lucidchart

這些工具也很適合用來繪製任何粗略的架構圖。

如果文章中有截圖或圖表，請上傳到 Imgur 的免費圖片託管服務，並以 Markdown 格式嵌入。請在方括號（[...]）中加入具描述性的文字，方便螢幕報讀軟體向視障讀者說明圖片內容。

技術文章中的標題該如何架構？

標題能讓內容更容易被快速掃視。使用 ##、### 和 #### 標籤來區分不同段落，標題應採用標題式大寫（Title Case）撰寫。

何時該用程式碼區塊，何時該用行內程式碼？

當程式碼有一行以上，或需要特別強調時，應使用程式碼區塊呈現。

若是指涉變數名稱，或是文中提到的簡短指令，則應使用行內程式碼（以反引號標示），例如在句子中提及呼叫某個函式時，應以行內程式碼格式標示函式名稱，而不是用一般引號包住。

技術寫作中的引言該如何格式化？

當引言長達兩行以上時，應使用區塊引言格式；若引言較短，或只是引用單一詞語或短句，則使用行內引號即可，並在後方標明出處。

謹慎使用強調格式

使用斜體來強調文字，或使用粗體來表示更強烈的強調，但不宜過度使用。

作者與編輯該如何溝通？

如果錯過截止日期該怎麼辦？

只要您有事先與 Draft.dev 溝通該次委稿的狀況，就不會因遲交而受罰。團隊可以提供技術協助或延長期限，但必須在截止日期前至少兩天提出。

好的做法是提前主動告知遇到的困難，並具體說明需要什麼協助；不好的做法則是等到截止日期當天才臨時告知進度落後，並要求延期。

若作者未主動溝通就錯過截止日期，將無法再獲得未來的委稿機會。

對編輯意見的回覆速度應該多快？

在仍有進行中的委稿期間，除非已事先告知無法配合的時段，否則應在 48 小時內回覆郵件。若稿件已逾期，則應在 24 小時內回覆。

好的做法是及時確認並回應編輯意見，並說明後續會如何調整；不好的做法則是拖到最後一刻才回覆，甚至已經逾期才發現郵件。

若作者對於進行中的委稿未能回覆郵件，將無法再獲得未來的委稿機會。

如何為您的部落格導入風格指南？

打造高品質的技術內容，需要一致性與明確的期望標準。雖然在部落格草創初期，風格指南或許不是必要之物，但隨著規模成長，它會成為極為寶貴的資產。

若想進一步討論部落格內容的合作，可以預約與 Draft.dev 團隊通話。

常見問題

技術部落格風格指南應該包含哪些內容？

技術部落格風格指南應包含語氣指引（第二人稱、口語化語氣）、內容標準（有力的開頭、有憑有據的論點、完整的結論）、格式規範（Markdown、標題層級、程式碼區塊），以及作者與編輯之間的溝通準則。

為什麼技術部落格需要風格指南？

當技術部落格擁有多位投稿者並持續擴大規模時，風格指南有助於維持一致性與品質。它能確保所有作者在語氣、格式與技術準確度上遵循相同標準，讓內容更專業，也更容易讓讀者理解。

技術內容中如何使用第二人稱撰寫？

以第二人稱撰寫，代表直接用「你」或「您」稱呼讀者，而非使用「我們」。例如，應寫成「您可以使用瀏覽器連上網站」，而非「我們可以使用我們的瀏覽器連上網站」，這樣能營造更具引導性、更吸引人的語氣。

什麼是技術寫作中「高高在上」的語言？

「高高在上」的語言指的是排他性的措辭，這類用語會預設讀者已具備某種知識，或使用「顯然」「只需要」等字眼，讓讀者感到自己知識不足。與其寫「顯然，你只需要從 master 分支建立分叉」，不如改寫成「從 main 分支建立分叉，並進行對應的修改」，會更具包容性。

技術部落格文章中的程式碼該如何格式化？

一行以上或需要特別強調的程式碼，應使用程式碼區塊呈現；若是提及變數名稱或文中的簡短指令，則應使用行內程式碼（以反引號標示）。例如，提及呼叫某函式時可用行內程式碼格式，但完整的函式或多行範例則應以完整的程式碼區塊呈現。

何時該為部落格建立風格指南？

當您開始與多位投稿者合作，或計畫擴大內容產出規模時，就應該建立風格指南。雖然在只有一兩位作者的草創初期並非必要，但隨著部落格成長，且需要在不同作者之間維持一致的品質時，風格指南就會變得極為重要。

原文

TL;DR: A technical blogging style guide ensures consistency across your content as you scale:

• Voice guidelines – Write in second person, use conversational language, avoid gatekeeping
• Content standards – Strong intros/conclusions, evidence-backed claims, proper citations
• Formatting conventions – Markdown formatting, proper headers, code blocks, image handling
• Communication protocols – Proactive updates on delays, timely email responses Essential for technical content agencies and engineering blogs maintaining quality at scale.

As your blog grows and you get more writers to contribute, you need to build documents and processes to help you maintain high quality and consistent style. To serve this goal, you should create a style guide to help writers and editors stay on the same page.

What Is a Technical Blogging Style Guide?

Generally, a style guide includes expectations for your contributors. Depending on your priorities, you may include more or less information than we do at Draft.dev, but our style guide should give you an excellent place to start. We send this style guide to all new contributors to ensure they are familiar with our expectations, and we refer to this guide throughout the editing process.

Of course, ours is not the only example of a technical writing style guide. If you’re looking to compare your options, check out Google’s developer documentation style guide, DigitalOcean’s technical writing guidelines, and some of the other guides here. If you’re creating a style guide, I’d recommend reading over several and deciding what you want to include in yours.

The big blog promotion checklist by Draft.dev.

The Draft.dev Technical Blogging Style Guide

At Draft.dev, we specialize in creating technical blog content for companies that want to reach software engineers. While most of our writers are software engineers first and authors second, we still expect them to follow consistent standards for each of our clients.

Below is our style guide, which is broken up into four sections.

How Should You Write Technical Content?

Write in Second Person

Speak to your readers directly using “you” and “your.” Avoid “we” and “our.”

Good:

You can use a web browser (like Chrome, Safari, or Edge) to access web sites on the internet.

Bad:

We can use our web browsers (like Chrome, Safari, or Edge) to access web sites on the internet.

Use Conversational, Business-Appropriate Language

Read your article out loud and ask yourself, “Would I talk like this at work?” Use your real-world experience, but avoid jargon when possible.

Good:

Experts agree that the internet was not the product of any individual mind, but a series of advances in networking and computer science.

Bad:

Many scholars would agree that, had it not been for active networks, the simulation of Lamport clocks might never have occurred. The notion that end-users synchronize with the investigation of Markov models is rarely outdated. A theoretical grand challenge in theory is the important unification of virtual machines and real-time theory. To what extent can web browsers be constructed to achieve this purpose?

Don’t Repeat Yourself

Eliminate wordiness. You shouldn’t repeat yourself when programming, and you shouldn’t repeat yourself when writing.

Good:

A lively debate rages among software developers. The contentious issue is: tabs or spaces?

Bad:

There is currently a lively, ongoing controversy among many computer scientists and other professional in the field of software development: theories are being spun and arguments are being conducted among them about whether the use of tabs to designate indentation in a document is superior to the use of spaces for the same purpose.

Avoiding Gatekeeping in Technical Writing

Write for an international audience of developers from a wide range of backgrounds, races, ethnicities, cultures, and experience levels. To that end, avoid language that is exclusionary or encourages “gatekeeping.”

Good:

Fork the main branch and make the appropriate changes.

Bad:

Obviously, you simply fork the master branch before making the appropriate changes.

Use the OpenGates Checklist here to ensure you’re not writing in a way that excludes others.

What Content Standards Should Technical Blogs Follow?

How Do You Write Effective Technical Introductions?

Every article should have a 1-3 paragraph introduction. A good intro needs to answer a few questions right away:

• What’s the pain point I’m addressing here? How do I hook my readers?
• What’s the solution to this problem?
• What am I going to do in this article?

Make sure your introduction is completed by letting the user know how you’re going to teach them to solve this pain point.

How Should You Support Claims in Technical Writing?

For every claim you make, ask yourself, “How can I prove this?” You can do this by:

• Including a link to a reputable article
• Including a quote from another source
• Citing an academic study
• Linking to the official documentation
• Interviewing knowledgeable professionals

Good:

While

$$Postgres can handle hundreds of columns$$

(https://nerderati.com/2017/01/03/postgresql-tables-can-have-at-most-1600-columns/), it might not be a good idea to take advantage of this feature.

Bad:

While I’m guessing Postgres can handle a lot of columns, it might not be a good idea to use more than a hundred if you can help it.

What Are the Rules for Citations and Copyright?

Written content that is copied directly from another source must be quoted and cited appropriately. Switching out a few words in a sentence is not enough to make the content original, so be sure to put everything in your own words.

Bad:

I’ve always thought that measuring programming progress by lines of code is akin to measuring aircraft building progress by measuring weight.

Good:

“Measuring programming progress by lines of code is like measuring aircraft building progress by weight.” – Bill Gates

The bar for using images is even higher. You may not use images from another website unless they expressly allow it. If you need stock images, use a site like Unsplash or one of the options here.

How Do You Write a Strong Technical Conclusion?

Every article should include a 1-2 paragraph conclusion. This should restate the thesis of the article and remind readers what they learned. It may also include other resources readers can reference to learn more.

Good:

While JSON data types come with some drawbacks, they are useful when you need more flexibility in your data structure. Thanks to Django’s native support for `jsonb`, you can get started using JSON data in your web applications without

$$learning all the native Postgres query operators$$

(https://www.postgresql.org/docs/current/functions-json.html).

Next time you need more flexibility in your data model and want to benefit from the strengths of Postgres give `jsonb` fields a try.

Distributing content on social media.

What Formatting Conventions Do Technical Blogs Use?

Why Write Technical Content in Markdown?

All articles should be written in Markdown and submitted in the Google Doc sent to you when you accept the assignment.

Good:

Markdown is a formatting language often *used by static site generators* and *blogs*. If you aren’t familiar with its syntax, you can

$$click here to learn more$$

(https://guides.github.com/features/mastering-markdown/).

How Should You Handle Screenshots and Diagrams?

If you need to circle something or add some text to a screenshot, please provide a screenshot annotated to the best of your ability, as well as an unmarked copy of the screenshot. This empowers our clients to redesign them according to their own branding if desired.

If you don’t already have a preference, we suggest using any of the following tools:

• dbdiagram.io
• Excalidraw
• Google Drawings
• Mermaid-JS
• Lucidchart

These are also all great options for any rough architectural diagrams you may need to make.

If you have screenshots or diagrams in your article, upload them to Imgur’s free image hosting service and embed them using Markdown. Include descriptive text inside the brackets ([...]) so that screen readers can describe the image.

Good:

!

$$A diagram showing different computer hardware$$

(https://i.imgur.com/hBE7ZF8.jpg)

Bad:


How Do You Structure Headers in Technical Posts?

Headers make your content more scannable. Use ##, ###, and #### header tags to denote different sections. Headings should be written in title case.

Good:

## How to Use JSON Fields in Your Python Application

…

### The Two JSON Formats Supported by Postgres

…

Bad (not title case):

## How to use JSON fields in your Python application

…

The two JSON formats supported by Postgres

…

When Should You Use Code Blocks vs Inline Code?

Use code blocks when the code is one or more lines long or deserves special emphasis.

Good:

“`

function snafu() {

return null;

}

“`

Bad:

`function snafu() {

return null;

}`

Use inline code when referring to a variable name or short command in context.

Good:

Call the `snafu()` method to exit and return to your command line.

Bad:

Call the “snafu()” method to exit and return to your command line.

How Do You Format Quotes in Technical Writing?

Use blockquotes when the quote is two or more lines long.

Good:

Some text leading up to the quote.

> “The field/element/path extraction operators return NULL, rather than failing, if the JSON input does not have the right structure to match the request; for example if no such key or array element exists.”

Some text after the quote.

Bad:

Some text leading up to the quote. “The field/element/path extraction operators return NULL, rather than failing, if the JSON input does not have the right structure to match the request; for example if no such key or array element exists.” Some text after the quote.

Use inline quotes when the quote is relatively short or when you’re referencing a single word or phrase.

Good:

“There’s nothing to see here,” said Davies.

Bad:

> “There’s nothing to see here.” – Davies

Use Emphasis Sparingly

Use italics to emphasize text or use bold to suggest strong emphasis.

Good:

There is *nothing* as important as using **spaces** to indent your code.

How to build a content engine.

How Should Writers and Editors Communicate?

What Should You Do When You Miss a Deadline?

You will not be penalized for late work if you’ve been in communication with us about the assignment. We can offer technical help and extensions, but you must ask two or more days before the due date.

Good:

Hey Karl,

I know the Postgres article is due next week, but I’m running into trouble. Would you be willing to hop on a quick call and explain the JSON fields in Postgres? Or do you have any resources that might help me out?

Bad:

Hey Karl,

I know my Postgres article was due today, but I’m not able to figure out the JSON fields in Postgres. Could I have an extension until next week to struggle with it more?

Authors that miss deadlines without communicating will not be eligible for future assignments.

How Quickly Should You Respond to Editorial Feedback?

While you have an open assignment, you should respond to emails within 48 hours unless you’ve notified us of your unavailability. If the assignment is overdue, you should respond within 24 hours.

Good:

Hey Karl,

Thanks for the update on this article. I’ll keep that in mind while I’m working on the piece this weekend.

Bad:

Hey Karl,

Sorry, but I didn’t see your email until today and I know the article is due now. I’ll try to incorporate your feedback before midnight if I can.

Authors that fail to respond to emails about open assignments will not be eligible for future assignments.

How Do You Implement a Style Guide for Your Blog?

Creating high-quality technical content requires consistency and clear expectations. While having a style guide may not be necessary during your blog’s early days, it’s an invaluable asset as you grow.

If you’d like to talk about creating content for your blog, you can schedule a call with us..

Frequently Asked Questions

What should a technical blogging style guide include?

A technical blogging style guide should include voice guidelines (second person, conversational tone), content standards (strong introductions, evidence-backed claims, proper conclusions), formatting conventions (Markdown, header hierarchy, code blocks), and communication protocols for writers and editors.

Why do technical blogs need a style guide?

Technical blogs need style guides to maintain consistency and quality as they scale with multiple contributors. Style guides ensure all writers follow the same standards for tone, formatting, and technical accuracy, making content more professional and easier for readers to follow.

How do you write in second person for technical content?

Writing in second person means addressing readers directly using 'you' and 'your' instead of 'we' and 'our.' For example, write 'You can use a web browser to access websites' rather than 'We can use our web browsers to access websites.' This creates a more engaging, instructional tone.

What is gatekeeping language in technical writing?

Gatekeeping language is exclusionary phrasing that assumes knowledge or uses terms like 'obviously' or 'simply' that make readers feel inadequate. Instead of writing 'Obviously, you simply fork the master branch,' write 'Fork the main branch and make the appropriate changes' to be more inclusive.

How should code be formatted in technical blog posts?

Use code blocks for one or more lines of code that deserve emphasis, and inline code (backticks) when referring to variable names or short commands within text. For example, write 'Call the `snafu()` method' for inline references, but use full code blocks for complete functions or multi-line examples.

When should you create a style guide for your blog?

Create a style guide when you start working with multiple contributors or plan to scale your content production. While not necessary in early days with one or two writers, a style guide becomes invaluable as your blog grows and you need to maintain consistent quality across different authors.