mirror of
https://github.com/LCTT/TranslateProject.git
synced 2024-12-29 21:41:00 +08:00
Xingyu.Wang
GitHub
commit
c8f7f844d7
@ -1,113 +0,0 @@
|
||||
[#]: collector: (lujun9972)
|
||||
[#]: translator: (HankChow)
|
||||
[#]: reviewer: ( )
|
||||
[#]: publisher: ( )
|
||||
[#]: url: ( )
|
||||
[#]: subject: (How to write effective documentation for your open source project)
|
||||
[#]: via: (https://opensource.com/article/20/3/documentation)
|
||||
[#]: author: (Kevin Xu https://opensource.com/users/kevin-xu)
|
||||
|
||||
How to write effective documentation for your open source project
|
||||
======
|
||||
Documentation quality can make the difference in people trying your
|
||||
project or passing it by.
|
||||
![A pink typewriter][1]
|
||||
|
||||
Unfortunately, good code won't speak for itself. Even the most elegantly designed and well-written codebase that solves the most pressing problem in the world won't just get adopted on its own. You, the open source creator, need to speak for your code and breathe life into your creation. That's where technical writing and documentation come in.
|
||||
|
||||
A project's documentation gets the most amount of traffic, by far. It's the place where people decide whether to continue learning about your project or move on. Thus, spending time and energy on documentation and technical writing, focusing on the most important section, "Getting Started," will do wonders for your project's traction.
|
||||
|
||||
Writing may feel uncomfortable, even daunting, to many of you. As engineers, we are trained more to write code than to write _about_ code. Many people also speak English as a second or even third language and may feel insecure or intimidated about writing in English. (I learned English as a second language, and my mother tongue is Mandarin Chinese, so I feel your pain.)
|
||||
|
||||
But we can't get around the reality that, if you want your project to have a broad, global reach, English is the language you must use. Don't fear. I wrote this post with those challenges in mind. You don't need to be the next Shakespeare to find the advice here useful.
|
||||
|
||||
### Five actionable writing tips
|
||||
|
||||
Here are five actionable writing tips you can apply today. They may seem painfully simple and obvious, yet they are ignored over and over again in technical writing.
|
||||
|
||||
1. **Use** [**active voice**][2]**:** Active voice: "You can change these configurations by…" vs. passive voice: "These configurations can be changed by…"
|
||||
2. **Use simple, short sentences:** While not open source, [Hemingway App][3] and [Grammarly][4] are both helpful tools.
|
||||
3. **Format for easy reading:** Use headings, bullet points, and links to break up information into chunks instead of long explanatory paragraphs.
|
||||
4. **Keep it visual:** Use tables and diagrams, not sentences, to represent information with multiple dimensions.
|
||||
5. **Mind your spelling and grammar:** Always, always, always spell check for typos and grammar check for polish.
|
||||
|
||||
|
||||
|
||||
By applying these tips consistently in your writing and editing workflow, you achieve two big goals: efficient communication and building trust.
|
||||
|
||||
* **Efficient communication:** Engineers don't want to read long-winded, meandering paragraphs in documentation (they have novels for that). They want to get technical information or instructions (when it's a guide) as efficiently as possible. Thus, your writing needs to be lean and useful. (That being said, it's fine to apply some humor, emojis, and "fluff" here and there to give your project some personality and make it more memorable. How exactly you do that will depend on _your_ personality.)
|
||||
* **Building trust:** The most valuable currency you must accrue, especially in the early days of building your project, is trust. Trust comes not only from your code quality but also from the quality of writing that talks about your code. Thus, please apply the same polish to your writing that you would to your code. This is the main reason for point 5 above (on spelling and grammar checks).
|
||||
|
||||
|
||||
|
||||
### Start with Getting Started documentation
|
||||
|
||||
With these fundamental techniques baked into your writing, the section you should spend the most time on in your documentation is the Getting Started section. This is, by far, the most important section and a classic example of the "[80/20 rule][5]" in action. Most of the web traffic to your project lands on your documentation, and most of _that_ lands on Getting Started. If it is well-constructed, you will get a new user right away. If not, the visitor will bounce and likely never come back.
|
||||
|
||||
How do you construct a good Getting Started section? I propose this three-step process:
|
||||
|
||||
1. **Make it a task:** An effective Getting Started guide should be task-oriented—a discrete mini-project that a developer can accomplish. It should _not_ contain too much information about the architectural design, core concept, and other higher-level information. A single, visual architectural overview is fine, but don't devote multiple paragraphs to how and why your project is the best-designed solution. That information belongs somewhere else (more on that below). Instead, the Getting Started section should mostly be a list of steps and commands to… well, get your project started!
|
||||
2. **Can be finished in less than 30 minutes:** The core takeaway here is that the time to completion should be as low as possible; 30 minutes is the upper bound. This time limit also assumes the user has relatively little context about your project. This is important to keep in mind. Most people who bother to go through your Getting Started guide are members of a technical audience with a vague understanding of your project but not much more than that. They are there to try something out before they decide to spend more time digging deeper. "Time to completion" is a metric you should measure to continuously improve your Getting Started guide.
|
||||
3. **Do something meaningful:** What "meaningful" means depends on the open source project. It is important to think hard about what that is, tightly define it into a task, and allow a developer who completes your Getting Started guide to achieve that meaningful task. This meaningful task must speak directly to your project's value; otherwise, it will leave developers feeling like they just wasted their time.
|
||||
|
||||
|
||||
|
||||
For inspiration: If you are a distributed database project, perhaps "meaningful" means the whole cluster remains available with no downtime after you kill some nodes. If you are a data analytics or business intelligence tool, perhaps "meaningful" means quickly generating a dashboard with different visualizations after loading some data. Whatever "meaningful" means to your project, it should be achievable quickly and locally on a laptop.
|
||||
|
||||
A good example is [Linkerd's Getting Started][6]. Linkerd is an open source service mesh for Kubernetes. I'm a novice in Kubernetes and even less familiar with service mesh. Yet, I completed Linkerd's Getting Started guide on my laptop without much hassle, and the experience gave me a taste of what operating a service mesh is all about.
|
||||
|
||||
The three-step process above could be a helpful framework for designing a highly efficient Getting Started section in a measurable way. It is also related to the time-to-value metric when it comes to [productizing your open source project][7].
|
||||
|
||||
### Other core components
|
||||
|
||||
Besides carefully calibrating and optimizing your Getting Started, there are five other top-level components that are necessary to build full-fledged documentation: architectural design, in-production usage guide, use cases, references, and roadmap.
|
||||
|
||||
* **Architectural design:** This is a deep-dive into your project's architecture and the rationales behind your design decisions, full of the details that you strategically glossed over in your Getting Started guide. This section is a big part of your overall [product marketing plan][8]. This section, usually filled with visuals and drawings, is meant to turn a casual hobbyist into an expert enthusiast who is interested in investing time in your project for the long term.
|
||||
* **In-production usage guide:** There is a world of difference between trying something out on a laptop and deploying it in production. Guiding a user who wants to use your project more seriously is an important next step. Demonstrating in-production operational knowledge is also how you attract your initial business customers who may like the promise of the technology but don't know or don't feel confident about using it in a production environment.
|
||||
* **Use cases:** The value of social proof is obvious, so listing your in-production adopters is important. The key here is to make sure this information is easy to find. It will likely be the second most popular link after Getting Started.
|
||||
* **References:** This section explains the project in detail and allows the user to examine and understand it under a microscope. It also functions as a dictionary where people look up information when needed. Some open source creators spend an inordinate amount of time spelling out every nuance and edge case of their project here. The motivation is understandable but unnecessary at the outset when your time is limited. It's more effective to reach a balance between detail and ways to get help: links to your community forum, Stack Overflow tag, or a separate FAQ page would do.
|
||||
* **Roadmap:** Laying out your future vision and plan with a rough timeline will keep users interested and incentivized for the long-term. Your project may not be perfect now, but you have a plan to perfect it. The Roadmap section is also a great place to get your community involved to build a strong ecosystem, so make sure you have a link that tells people how to voice their thoughts and opinions regarding the roadmap. (I'll write about community-building specifics in the future.)
|
||||
|
||||
|
||||
|
||||
You may not have all these components fully fleshed out yet, and some parts may materialize later than others, especially the use cases. However, be intentional about building these out over time. Addressing these five elements is the critical next step to your users' journey into your project, assuming they had a good experience with Getting Started.
|
||||
|
||||
One last note: include a clear one-sentence statement on what license you are using (probably in Getting Started, README, or somewhere else highly visible). This small touch will make vetting your project for adoption from the end user's side much more efficient.
|
||||
|
||||
### Spend 20% of your time writing
|
||||
|
||||
Generally, I recommend spending 10–20% of your time writing. Putting it in context: If you are working on your project full time, it's about half a day to one full day per week.
|
||||
|
||||
The more nuanced point here is you should work writing into your normal workflow, so it becomes a routine, not an isolated chore. Making incremental progress over time, rather than doing all the writing in one giant sitting, is what will help your project reach that ultimate goal: traction and trust.
|
||||
|
||||
* * *
|
||||
|
||||
_Special thanks to [Luc Perkins][9], developer advocate at the Cloud Native Computing Foundation, for his invaluable input._
|
||||
|
||||
_This article originally appeared on_ _[COSS Media][10]_ _and is republished with permission._
|
||||
|
||||
Nigel Babu offers 10 tips for taking your project's documentation to the next level.
|
||||
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
via: https://opensource.com/article/20/3/documentation
|
||||
|
||||
作者：[Kevin Xu][a]
|
||||
选题：[lujun9972][b]
|
||||
译者：[译者ID](https://github.com/译者ID)
|
||||
校对：[校对者ID](https://github.com/校对者ID)
|
||||
|
||||
本文由 [LCTT](https://github.com/LCTT/TranslateProject) 原创编译，[Linux中国](https://linux.cn/) 荣誉推出
|
||||
|
||||
[a]: https://opensource.com/users/kevin-xu
|
||||
[b]: https://github.com/lujun9972
|
||||
[1]: https://opensource.com/sites/default/files/styles/image-full-size/public/lead-images/osdc-docdish-typewriter-pink.png?itok=OXJBtyYf (A pink typewriter)
|
||||
[2]: https://www.grammar-monster.com/glossary/active_voice.htm
|
||||
[3]: http://www.hemingwayapp.com/
|
||||
[4]: https://www.grammarly.com/
|
||||
[5]: https://en.wikipedia.org/wiki/Pareto_principle
|
||||
[6]: https://linkerd.io/2/getting-started/
|
||||
[7]: https://opensource.com/article/19/11/products-open-source-projects
|
||||
[8]: https://opensource.com/article/20/2/product-marketing-open-source-project
|
||||
[9]: https://twitter.com/lucperkins
|
||||
[10]: https://coss.media/open-source-documentation-technical-writing-101/
|
||||
@ -0,0 +1,106 @@
|
||||
[#]: collector: (lujun9972)
|
||||
[#]: translator: (HankChow)
|
||||
[#]: reviewer: ( )
|
||||
[#]: publisher: ( )
|
||||
[#]: url: ( )
|
||||
[#]: subject: (How to write effective documentation for your open source project)
|
||||
[#]: via: (https://opensource.com/article/20/3/documentation)
|
||||
[#]: author: (Kevin Xu https://opensource.com/users/kevin-xu)
|
||||
|
||||
如何为你的开源项目编写实用的文档
|
||||
======
|
||||
一份优质的文档可以让很多用户对你的项目路人转粉。
|
||||
|
||||
![A pink typewriter][1]
|
||||
|
||||
好的代码很多时候并不代表一切。或许你能用最精巧的代码解决了世界上最迫切需要解决的问题，但如果你作为一个开源开发者，没能用准确的语言将你的作品公之于世，你的代码也只能成为沧海遗珠。因此，技术写作和文档编写是很重要的技能。
|
||||
|
||||
一般来说，项目中的文档是最受人关注的部分，很多用户会通过文档来决定自己是否应该对某个项目开始学习或研究。所以，我们不能忽视技术写作和文档编写的工作，尤其要重点关注其中的“入门”部分，这会对你项目的发展起到关键性的作用。
|
||||
|
||||
对于很多人来说，写作是一件令人厌烦甚至恐惧的事情。我们这些工程师出身的人，学习“写代码”比学习“为代码写文档”明显更多。不少人会把英语作为自己的第二语言或者第三语言，他们可能会对英语写作感到不安全甚至害怕（我的母语是汉语，英语是作为我的第二语言学习的，所以我也能感受到这种痛苦）。
|
||||
|
||||
但如果你希望自己的项目能在全球范围内产生一定的影响力，英语就是你必须使用的语言，这是一个无法避免的现实。但不必害怕，我在写这篇文章的时候就考虑到了这些可能带来的挑战，并给出了我的一些建议。
|
||||
|
||||
### 五条有用的写作建议
|
||||
|
||||
这五条建议你马上就可以用起来，尽管看起来似乎有些浅显，但在技术写作时却经常被忽视。
|
||||
|
||||
1. 使用[主动语态][2]：感受一下主动语态下的“你可以这样更改配置（You can change these configurations by…）”和被动语态下的“配置可以这样更改（These configurations can be changed by…）”有什么不同之处。
|
||||
2. 使用简洁明了的句子：可以借助 [Hemingway App][3] 或者 [Grammarly][4] 这样的工具，尽管它们并不开源。
|
||||
3. 保持条理性：你可以在文档中通过写标题、划重点、引链接等方式，把各类信息划分为不同的部分，避免将所有内容都杂糅在一大段冗长的文字当中。
|
||||
4. 提高可读性：除了单纯的文字之外，运用图表也是从多种角度表达的手段之一。
|
||||
5. 注意拼写和语法：必须记得检查文档中是否有拼写错误或者语法错误。
|
||||
|
||||
只要在文档的写作和编辑过程中应用到这些技巧，你就能够和读者建立起沟通和信任。
|
||||
|
||||
* 高效沟通：对于工程师们来说，阅读长篇大论的冗长文字，还不如去看小说。在阅读技术文档时，他们总是希望能够从中快速准确地获取到有用的信息。因此，技术文档的最佳风格应该是精简而有效的，不过这并不代表文档中不能出现类似幽默、emoji 甚至段子这些东西，这些元素可以当你的文档更有个性、更使人印象深刻。当然，具体的实现方式就因人而异了
|
||||
* 建立信任：你需要取得文档读者们的信任，这在一个项目的前期尤为重要。读者对你的信任除了来源于你代码的质量，还跟你文档编写的质量有关。所以你不仅要打磨代码，还要润色好相关的文档，这也是上面第 5 点建议拼写和语法检查的原因。
|
||||
|
||||
### 如何开始编写文档
|
||||
|
||||
现在，最需要花费功夫的应该就是“入门”部分了，这是一篇技术文档最重要的部分，[二八定律][5]在这里得到了充分体现：访问一个项目的大部分流量都会落在项目文档上，而访问项目文档的大部分流量则会落在文档的“入门”部分中。因此，如果文档的“入门”部分写得足够好，项目就会吸引到很多用户，反之，用户会对你的项目敬而远之。
|
||||
|
||||
那么如何写好“入门”部分呢？我建议按照以下三步走：
|
||||
|
||||
1. 任务化：入门指南应该以任务为导向。这里的任务指的是对于开发者来说可以完成的离散的小项目，而不应该包含太多涉及到体系结构、核心概念等的抽象信息，因此在“入门”部分只需要提供一个简单明了的概述就可以了。也不要在“入门”部分大谈这个项目如何优秀地解决了问题，这个话题可以放在文档中别的部分进行说明。总而言之，“入门”部分最好是给出一些主要的操作步骤，这样显得开门见山。
|
||||
2. 30 分钟内能够完成：这一点的核心是耗时尽可能短，不宜超过 30 分钟，这个时间上限是考虑到用户可能对你的项目并不了解。这一点很重要，大部分愿意浏览文档的人都是有技术基础的，但对你的项目也仅仅是一知半解。首先让这些读者尝试进行一些相关操作，在收到一定效果后，他们才会愿意花更多时间深入研究整个项目。因此，你可以从耗时这个角度来评估你的文档“入门”部分有没有需要改进之处。
|
||||
3. 有意义的任务：这里“有意义”的含义取决于你的开源项目。最重要的是认真思考并将“入门”部分严格定义为一项任务，然后交给你的读者去完成。这个项目的价值应该在这项有意义的任务中有所体现，不然读者可能会感觉这是一个浪费时间的行为。
|
||||
|
||||
提示：假如你的项目是一个分布式数据库，那么达到“整个集群在某些节点故障的情况下可以不中断地保持可用”的目标就可以认为是“有意义”的；加入你的项目是一个数据分析工具或者是商业智能工具，“有意义”的目标也可以是“加载数据后能快速生成多种可视化效果的仪表板”。总之，无论你的项目需要达到什么“有意义”的目标，都应该能在笔记本电脑上本地快速实现。
|
||||
|
||||
[Linkerd 入门][6]就是一个很好的例子。Linkerd 是 Kubernetes 的开源<ruby>服务网格<rt>Service Mesh</rt></ruby>，当时我对 Kubernetes 了解并不多，也不熟悉服务网格。但我在自己的笔记本电脑上很轻松地就完成了其中的任务，同时也加深了对服务网格的理解。
|
||||
|
||||
上面提到的三步过程是一个很有用的框架，对一篇文档“入门”部分的设计和量化评估很有帮助。今后你如果想将你的[开源项目产品化][7]，这个框架还可能对<ruby>实现价值的时间<rt>time-to-value</rt></ruby>产生影响。
|
||||
|
||||
### Other core components
|
||||
|
||||
认真写好“入门”部分之后，你的文档中还需要有这五个部分：架构设计、生产环境使用指导、使用案例、参考资料以及未来展望，这五个部分在一份完整的文档中是必不可少的。
|
||||
|
||||
* 架构设计：这一部分需要深入探讨整个项目架构设计的依据，“入门”部分中一笔带过的那些关键细节就应该在这里体现。在产品化过程中，这个部分将会是[产品推广计划][8]的核心，因此通常会包含一些可视化呈现的内容，期望的效果是让更多用户长期参与到项目中来。
|
||||
* 生产环境使用指导：对于同一个项目，在生产环境中部署比在笔记本电脑上部署要复杂得多。因此，指导用户认真使用就尤为重要。同时，有些用户可能对项目很感兴趣，但对生产环境下的使用有所顾虑，而指导和展示的过程则正好能够吸引到这类潜在的用户。
|
||||
* 使用案例：<ruby>社会认同<rt>social proof</rt></ruby>的力量是有目共睹的，所以很有必要列出正在生产环境使用这个项目的其他用户，并把这些信息摆放在显眼的位置。这个部分的浏览量甚至仅次于“入门”部分。
|
||||
* 参考资料：这个部分是对项目的一些详细说明，让用户得以进行详细的研究以及查阅相关信息。一些开源作者会在这个部分事无巨细地列出项目中的每一个细节和<ruby>边缘情况<rt>edge case</rt></ruby>，这种做法可以理解，但不推荐在项目初期就在这个部分花费过多的时间。你可以采取更折中的方式，在质量和效率之间取得平衡，例如提供一些相关社区的链接、Stack Overflow 上的标签或单独的 FAQ 页面。
|
||||
* 未来展望：你需要制定一个简略的时间表，规划这个项目的未来发展方向，这会让用户长期保持兴趣。尽管项目在当下可能并不完美，但要让用户知道你仍然有完善这个项目的计划。这个部分也能让整个社区构建一个强大的生态，因此还要向用户提供表达他们对未来展望的看法的交流区。
|
||||
|
||||
以上这几个部分或许还没有在你的文档中出现，甚至可能会在后期才能出现，尤其是“使用案例”部分。尽管如此，还是应该在文档中逐渐加入这些部分。如果用户对“入门”部分已经感觉良好，那以上这几个部分将会提起用户更大的兴趣。
|
||||
|
||||
最后，请在“入门”部分、README 文件或其它显眼的位置注明整个项目所使用的许可证。这个细节会让你的项目更容易通过终端用户的审核。
|
||||
|
||||
### 花 20% 的时间写作
|
||||
|
||||
一般情况下，我建议把整个项目 10% 到 20% 的时间用在文档写作上。也就是说，如果你是全职进行某一个项目的，文档写作需要在其中占半天到一天。
|
||||
|
||||
再细致一点，应该将写作纳入到常规的工作流程中，这样它就不再是一件孤立的琐事，而是日常的事务。文档写作应该随着工作进度同步进行，切忌将所有写作任务都堆积起来最后完成，这样才可以帮助你的项目达到最终目标：吸引用户、获得信任。
|
||||
|
||||
* * *
|
||||
|
||||
_特别鸣谢云原生计算基金会的布道师 [Luc Perkins][9] 给出的宝贵意见。_
|
||||
|
||||
_本文首发于_ _[COSS Media][10]_ _并经许可发布。_
|
||||
|
||||
Nigel Babu 提供了 10 条帮助编写项目文档的有用技巧。
|
||||
|
||||
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
via: https://opensource.com/article/20/3/documentation
|
||||
|
||||
作者：[Kevin Xu][a]
|
||||
选题：[lujun9972][b]
|
||||
译者：[HankChow](https://github.com/HankChow)
|
||||
校对：[校对者ID](https://github.com/校对者ID)
|
||||
|
||||
本文由 [LCTT](https://github.com/LCTT/TranslateProject) 原创编译，[Linux中国](https://linux.cn/) 荣誉推出
|
||||
|
||||
[a]: https://opensource.com/users/kevin-xu
|
||||
[b]: https://github.com/lujun9972
|
||||
[1]: https://opensource.com/sites/default/files/styles/image-full-size/public/lead-images/osdc-docdish-typewriter-pink.png?itok=OXJBtyYf (A pink typewriter)
|
||||
[2]: https://www.grammar-monster.com/glossary/active_voice.htm
|
||||
[3]: http://www.hemingwayapp.com/
|
||||
[4]: https://www.grammarly.com/
|
||||
[5]: https://en.wikipedia.org/wiki/Pareto_principle
|
||||
[6]: https://linkerd.io/2/getting-started/
|
||||
[7]: https://opensource.com/article/19/11/products-open-source-projects
|
||||
[8]: https://opensource.com/article/20/2/product-marketing-open-source-project
|
||||
[9]: https://twitter.com/lucperkins
|
||||
[10]: https://coss.media/open-source-documentation-technical-writing-101/
|
||||
Loading…
Reference in New Issue
Block a user