mirror of
https://github.com/LCTT/TranslateProject.git
synced 2024-12-26 21:30:55 +08:00
geekpi
GitHub
commit
8514bac789
@ -1,83 +0,0 @@
|
||||
[#]: subject: "3 reasons to host a docathon for your open source project"
|
||||
[#]: via: "https://opensource.com/article/23/4/open-source-docathon"
|
||||
[#]: author: "Lydie Modé-Malivert https://opensource.com/users/lmalivert"
|
||||
[#]: collector: "lkxed"
|
||||
[#]: translator: "geekpi"
|
||||
[#]: reviewer: " "
|
||||
[#]: publisher: " "
|
||||
[#]: url: " "
|
||||
|
||||
3 reasons to host a docathon for your open source project
|
||||
======
|
||||
|
||||
Your open source project's documentation is essential to your customers. Your target audience must understand the purpose of your project and how to use it, and documentation is what bridges that gap. A project is rarely ever truly done, so it's equally important for resources to be maintained and updated with your project's continuous improvement.
|
||||
|
||||
But what happens when you have lots of documentation to maintain but lack the resources to keep it current? The answer is pretty simple: Host a docathon!
|
||||
|
||||
### What is a docathon?
|
||||
|
||||
A docathon is like a hackathon. A hackathon is an event where engineers and community leaders gather to improve or add new features to an existing application. In a docathon, the same kind of collaboration focuses on improving documentation.
|
||||
|
||||
**[ Learn about writing [Docs as Code][1]. ]**
|
||||
|
||||
A docathon can fill gaps within content, restructure large documentation sets, fix broken links, or just correct typos. The intent behind hosting a docathon is to improve a large amount of documentation in a relatively brief timeframe.
|
||||
|
||||
Some examples of product documentation include:
|
||||
|
||||
- Training manuals
|
||||
- User manuals
|
||||
- Installation guides
|
||||
- Troubleshooting guides
|
||||
- Quickstart guides
|
||||
- [API][2] documentation
|
||||
- Tutorials
|
||||
|
||||
At my organization, our documentation team hosted a docathon and successfully revamped a 102-page installation guide. The docathon enabled us to focus on the project's scope, which was reorganizing for simplicity, removing duplicate content, and following the customer journey. Hosting a docathon left a lasting impression on my team and improved customer success.
|
||||
|
||||
### 3 things you can achieve with a docathon
|
||||
|
||||
Here are my top three reasons to host a docathon:
|
||||
|
||||
#### 1. No more backlog
|
||||
|
||||
Most documentation must evolve along with the product it supports. As the product changes or updates, so must the documentation. In some cases, documentation teams release new versions of their documentation alongside the engineering team's release cycle. As priorities within a team change and [GA releases][4] continue, documentation teams face the challenge of keeping up with new features, bug fixes, and tasks to complete. The changes that get left behind become part of a backlog—an accumulation of work that needs to be completed at a later time.
|
||||
|
||||
> **Docathon tip:**During a docathon, participants can triage backlog items and complete them as they progress through the list. Non-technical participants can work on fixes related to typos, broken links, and other text-related issues.
|
||||
|
||||
#### 2. Revamp large-scale guides
|
||||
|
||||
By the time your documentation team realizes it's time to revamp a guide, it's probably several chapters in and hundreds of pages deep. Once the content plan has been developed, the complexity of restructuring begins. Restructuring a large amount of documentation is not for the faint of heart.
|
||||
|
||||
> **Docathon tip:** Assemble a team to lead the docathon and provide incentives for organization-wide participation from different teams or departments. Depending on the scope of work and time constraints, your team can successfully restructure an entire guide in less time than you probably expect.
|
||||
|
||||
#### 3. Collaboration between cross-functional teams
|
||||
|
||||
It is common for different groups within an organization to work in isolation. Engineering, product, customer support, marketing, and documentation teams may not collaborate on projects as often as they should.
|
||||
|
||||
Imagine hosting an event where each team member can use their expertise to improve product documentation. Docathons foster subject matter expert (SME) diversity, real-time collaboration, and communication. They also allow for an inclusive environment where individuals residing in different geographical locations can participate in person or remotely. Your documentation receives the undivided attention of experts with different viewpoints and specializations, minimizing isolated siloes, unconscious bias, and burnout.
|
||||
|
||||
> **Docathon tip:** Enable cross-functional teams to come together for a common cause.
|
||||
|
||||
### Documentation marathon
|
||||
|
||||
The next time your team has a seemingly insurmountable backlog or is tasked with restructuring a huge documentation project, consider hosting a docathon. It's easy, and its productivity may surprise you. For more information on hosting an event like this, read Tiffany Long's excellent [10-step guide to hosting a hackathon][6].
|
||||
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
via: https://opensource.com/article/23/4/open-source-docathon
|
||||
|
||||
作者：[Lydie Modé-Malivert][a]
|
||||
选题：[lkxed][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/lmalivert
|
||||
[b]: https://github.com/lkxed/
|
||||
[1]: https://opensource.com/article/22/10/docs-as-code
|
||||
[2]: https://www.redhat.com/en/topics/api/what-are-application-programming-interfaces?intcmp=7013a000002qLH8AAM
|
||||
[3]: https://opensource.com/article/23/3/community-documentation
|
||||
[4]: https://opensource.com/article/19/7/what-golden-image
|
||||
[5]: https://www.redhat.com/en/resources/build-a-resilient-it-culture-ebook?intcmp=7013a000002qLH8AAM
|
||||
[6]: https://opensource.com/downloads/hackathon-guide?intcmp=7013a000002qLH8AAM
|
||||
@ -0,0 +1,80 @@
|
||||
[#]: subject: "3 reasons to host a docathon for your open source project"
|
||||
[#]: via: "https://opensource.com/article/23/4/open-source-docathon"
|
||||
[#]: author: "Lydie Modé-Malivert https://opensource.com/users/lmalivert"
|
||||
[#]: collector: "lkxed"
|
||||
[#]: translator: "geekpi"
|
||||
[#]: reviewer: " "
|
||||
[#]: publisher: " "
|
||||
[#]: url: " "
|
||||
|
||||
为你的开源项目举办一场文档马拉松的 3 个理由
|
||||
======
|
||||
|
||||
你的开源项目的文档对你的客户至关重要。你的目标受众必须了解你的项目的目的和如何使用它，而文档是弥合这一差距的工具。一个项目很少有真正完成的时候，所以随着你项目的不断改进，资源的维护和更新同样重要。
|
||||
|
||||
但是，当你有大量的文档需要维护，但又缺乏资源来保持它的时效性时，会发生什么？答案很简单： 举办一个文档马拉松！
|
||||
|
||||
### 什么是文档马拉松？
|
||||
|
||||
文档马拉松就像黑客马拉松。黑客马拉松是工程师和社区领袖聚集在一起改进或添加新功能到一个现有的应用的活动。在一个文档马拉松中，同样的合作集中在改进文档上。
|
||||
|
||||
文档马拉松可以填补内容上的空白，重组大型文档集，修复失效的链接，或者只是纠正错别字。举办文档马拉松的目的是为了在相对短的时间内改进大量的文档。
|
||||
|
||||
一些产品文档的例子包括：
|
||||
|
||||
- 培训手册
|
||||
- 用户手册
|
||||
- 安装指南
|
||||
- 故障排除指南
|
||||
- 快速入门指南
|
||||
- [API][2] 文档
|
||||
- 教程
|
||||
|
||||
在我的组织里，我们的文档团队举办了一次文档马拉松，成功地修改了 102 页的安装指南。这次文档马拉松使我们能够专注于项目的范围，即重新组织简化，删除重复的内容，并遵循客户旅程。举办文档马拉松给我的团队留下了深刻的印象，并提高了客户的成功率。
|
||||
|
||||
### 3 件你可以通过文档马拉松实现的事情
|
||||
|
||||
以下是我举办文档马拉松的三大理由：
|
||||
|
||||
#### 1. 没有更多的积压
|
||||
|
||||
大多数文档必须随着它所支持的产品的发展而发展。随着产品的变化或更新，文档也必须如此。在某些情况下，文档团队与工程团队的发布周期一起发布新版本的文档。随着团队内优先级的改变和 [GA 发布][4]的继续，文档团队面临着跟上新功能、错误修复和任务完成的挑战。被遗弃的变化成为积压的一部分，一种需要在以后完成的工作的积累。
|
||||
|
||||
> **文档马拉松提示：**在文档马拉松期间，参与者可以对积压的项目进行分流，并在列表中完成它们。非技术性的参与者可以从事与错别字、失效的链接和其他文本相关问题的修复工作。
|
||||
|
||||
#### 2. 改造大型指南
|
||||
|
||||
当你的文档团队意识到是时候修改指南的时候，它可能已经有好几章，好几百页了。一旦制定了内容计划，重组的复杂性就开始了。重组大量的文档并不适合胆小的人。
|
||||
|
||||
> **文档马拉松提示：** 组建一个团队来领导文档马拉松，并为不同团队或部门的全组织参与提供奖励。根据工作范围和时间限制，你的团队可以在比你预期更短的时间内成功重组整个指南。
|
||||
|
||||
#### 3. 跨职能团队之间的合作
|
||||
|
||||
一个组织内的不同小组孤立地工作是很常见的。工程、产品、客户支持、营销和文档团队可能没有像他们应该的那样经常在项目上进行协作。
|
||||
|
||||
想象一下，举办一次活动，每个团队成员都可以利用他们的专业知识来改善产品文档。文档马拉松促进了主题专家（SME）的多样性、实时协作和沟通。它们还允许一个包容性的环境，居住在不同地理位置的人可以亲自或远程参与。你的文件会得到具有不同观点和专业的专家的关注，最大限度地减少孤立的孤岛、无意识的偏见和倦怠。
|
||||
|
||||
> **文档马拉松提示：**使跨职能的团队为了一个共同的事业走到一起。
|
||||
|
||||
### 文档马拉松
|
||||
|
||||
下一次，当你的团队有一个似乎无法克服的积压工作，或者被赋予重组一个巨大的文档项目的任务时，考虑举办一个文档马拉松。这很容易，而且它的生产力可能会让你吃惊。关于举办这样的活动的更多信息，请阅读 Tiffany Long 的优秀的[举办黑客马拉松的 10 步指南][6]。
|
||||
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
via: https://opensource.com/article/23/4/open-source-docathon
|
||||
|
||||
作者：[Lydie Modé-Malivert][a]
|
||||
选题：[lkxed][b]
|
||||
译者：[geekpi](https://github.com/geekpi)
|
||||
校对：[校对者ID](https://github.com/校对者ID)
|
||||
|
||||
本文由 [LCTT](https://github.com/LCTT/TranslateProject) 原创编译，[Linux中国](https://linux.cn/) 荣誉推出
|
||||
|
||||
[a]: https://opensource.com/users/lmalivert
|
||||
[b]: https://github.com/lkxed/
|
||||
[2]: https://www.redhat.com/en/topics/api/what-are-application-programming-interfaces?intcmp=7013a000002qLH8AAM
|
||||
[3]: https://opensource.com/article/23/3/community-documentation
|
||||
[4]: https://opensource.com/article/19/7/what-golden-image
|
||||
[5]: https://www.redhat.com/en/resources/build-a-resilient-it-culture-ebook?intcmp=7013a000002qLH8AAM
|
||||
[6]: https://opensource.com/downloads/hackathon-guide?intcmp=7013a000002qLH8AAM
|
||||
Loading…
Reference in New Issue
Block a user