mirror of
https://github.com/LCTT/TranslateProject.git
synced 2025-02-03 23:40:14 +08:00
Xingyu.Wang
GitHub
commit
1d08f42eab
@ -1,91 +0,0 @@
|
||||
[#]: subject: (A DevOps guide to documentation)
|
||||
[#]: via: (https://opensource.com/article/21/3/devops-documentation)
|
||||
[#]: author: (Will Kelly https://opensource.com/users/willkelly)
|
||||
[#]: collector: (lujun9972)
|
||||
[#]: translator: (Veryzzj)
|
||||
[#]: reviewer: ( )
|
||||
[#]: publisher: ( )
|
||||
[#]: url: ( )
|
||||
A DevOps guide to documentation
|
||||
======
|
||||
|
||||
Bring your documentation writing into the DevOps lifecycle.
|
||||
![Typewriter with hands][1]
|
||||
|
||||
DevOps is challenging technical documentation norms like at no other time in IT history. From automation to increased delivery velocity to dismantling the waterfall software development lifecycle model, these all spell the need for making dramatic changes to business and the philosophy of technical documentation.
|
||||
|
||||
Here are some ways DevOps is influencing technical documentation.
|
||||
|
||||
### The technical writer's changing role
|
||||
|
||||
The technical writer's role must adapt to DevOps. The good news is that many technical writers are already embedded in development teams, and they may have a leg up by already having collaborative relationships and growing knowledge of the product.
|
||||
|
||||
But you have some pivoting to do if your technical writers are used to working in siloes and relying on drafts written by subject matter experts as the basis for documentation.
|
||||
|
||||
Make the investments to ensure your documentation and other project-related content development efforts gain the tools, structure, and support they require. Start by changing your [technical writer hiring practices][2]. Documentation at the [speed of DevOps][3] requires rethinking your content strategy and breaking down longstanding silos between your DevOps team and the technical writer assigned to support the project.
|
||||
|
||||
DevOps also causes development teams to break away from the rigors of traditional documentation practices. Foremost, documentation's [definition of done][4] must change. Some corporate cultures make the technical writer a passive participant in software development. DevOps makes new demands—as the DevOps cultural transformation goes, so does the technical writer's role. Writers will need (and must adjust to) the transparency DevOps offers. They must integrate into DevOps teams. Depending on how an organization casts the role, bringing the technical writer into the team may present skillset challenges.
|
||||
|
||||
### Documentation standards, methodologies, and specifications
|
||||
|
||||
While DevOps has yet to influence technical documentation itself, the open source community has stepped up to help with application programming interface (API) documentation that's finding use among DevOps teams in enterprises of all sizes.
|
||||
|
||||
Open source specifications and tools for documenting APIs are an exciting area to watch. I'd like to think it is due to the influence of [Google Season of Docs][5], which gives open source software projects access to professional technical writing talent to tackle their most critical documentation projects.
|
||||
|
||||
Open source APIs are available and need to become part of the DevOps documentation discussion. The importance of cloud-native application integration requirements is on the rise. The [OpenAPI specification][6]—an open standard for defining and documenting an API—is a good resource for API documentation in DevOps environments. However, a significant criticism is that the specification can make documentation time-consuming to create and keep current.
|
||||
|
||||
There were brief attempts to create a [Continuous Documentation][7] methodology. There was also a movement to create a [DocOps][8] Framework that came out of CA (now Broadcom). Despite its initial promise, DocOps never caught on as an industry movement.
|
||||
|
||||
The current state of DevOps documentation standards means your DevOps teams (including your technical writer) need to begin creating documentation at the earliest stages of a project. You do this by adding documentation as both an agile story and (just as important) as a management expectation; you enforce it by tying it to annual performance reviews.
|
||||
|
||||
### Documentation tools
|
||||
|
||||
DevOps documentation authoring should occur online in a format or a platform accessible to all team members. MediaWiki, DokuWiki, TikiWiki, and other [open source wikis][9] offer DevOps teams a central repository for authoring and maintaining documentation.
|
||||
|
||||
Let teams choose their wiki just as you let them choose their other continuous integration/continuous development (CI/CD) toolchains. Part of the power of open source wikis is their extensibility. For example, DokuWiki includes a range of extensions you can install to create an authoring platform that meets your DevOps team's authoring requirements.
|
||||
|
||||
If you're ambitious enough to bolster your team's authoring and collaboration capabilities, [Nextcloud][10] (an open source cloud collaboration suite) is an option for putting your DevOps teams online and giving them the tools they need to author documentation.
|
||||
|
||||
### DevOps best practices
|
||||
|
||||
Documentation also plays a role in DevOps transformation. You're going to want to document the best practices that help your organization realize efficiency and process gains from DevOps. This information is too important to communicate only by word of mouth across your DevOps teams. Documentation is a unifying force if your organization has multiple DevOps teams; it promotes standardization of best practices and sets you up to capture and benchmark metrics for code quality.
|
||||
|
||||
Often it's developers who shoulder the work of documenting DevOps practices. Even if their organizations have technical writers, they might work across development teams. Thus, it's important that developers and sysadmins can capture, document, and communicate their best practices. Here are some tips to get that effort going in the right direction:
|
||||
|
||||
* Invest the time upfront to create a standard template for your DevOps best practices. Don't fall into the trap of copying a template you find online. Interview your stakeholders and teams to create a template that meets your team's needs.
|
||||
* Look for ways to be creative with information gathering, such as recording your team meetings and using chat system logs to serve as a foundation for your documentation.
|
||||
* Establish a wiki for publishing your best practices. Use a wiki that lets you maintain an audit trail of edits and updates. Such a platform sets your teams up to update and maintain best practices as they change.
|
||||
|
||||
It's smart to document dependencies as you build out your CI/CD toolchains. Such an effort pays off when you onboard new team members. It's also a little bit of insurance when a team member forgets something.
|
||||
|
||||
Finally, automation is enticing to DevOps stakeholders and practitioners alike. It's all fun and games until automation breaks. Having documentation for automation run books, admin guides, and other things in place (and up to date) means your staff can get automation working again regardless of when it breaks down.
|
||||
|
||||
### Final thoughts
|
||||
|
||||
DevOps is a net positive for technical documentation. It pulls content development into the DevOps lifecycle and breaks down the siloes between developers and technical writers within the organizational culture. Without the luxury of a technical writer, teams get the tools to accelerate their document authoring's velocity to match the speed of DevOps.
|
||||
|
||||
What is your organization doing to bring documentation into the DevOps lifecycle? Please share your experience in the comments.
|
||||
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
via: https://opensource.com/article/21/3/devops-documentation
|
||||
|
||||
作者：[Will Kelly][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/willkelly
|
||||
[b]: https://github.com/lujun9972
|
||||
[1]: https://opensource.com/sites/default/files/styles/image-full-size/public/lead-images/typewriter-hands.jpg?itok=oPugBzgv (Typewriter with hands)
|
||||
[2]: https://opensource.com/article/19/11/hiring-technical-writers-devops
|
||||
[3]: https://searchitoperations.techtarget.com/opinion/Make-DevOps-documentation-an-integral-part-of-your-strategy?_ga=2.73253915.980148481.1610758264-908287796.1564772842
|
||||
[4]: https://www.agilealliance.org/glossary/definition-of-done
|
||||
[5]: https://developers.google.com/season-of-docs
|
||||
[6]: https://swagger.io/specification/
|
||||
[7]: https://devops.com/continuous-documentation
|
||||
[8]: https://www.cmswire.com/cms/information-management/the-importance-of-docops-in-the-new-era-of-business-027489.php
|
||||
[9]: https://opensource.com/article/20/7/sharepoint-alternative
|
||||
[10]: https://opensource.com/article/20/7/nextcloud
|
||||
92
translated/tech/20210330 A DevOps guide to documentation.md
Normal file
92
translated/tech/20210330 A DevOps guide to documentation.md
Normal file
@ -0,0 +1,92 @@
|
||||
[#]: subject: "A DevOps guide to documentation"
|
||||
[#]: via: "https://opensource.com/article/21/3/devops-documentation"
|
||||
[#]: author: "Will Kelly https://opensource.com/users/willkelly"
|
||||
[#]: collector: "lujun9972"
|
||||
[#]: translator: "Veryzzj"
|
||||
[#]: reviewer: " "
|
||||
[#]: publisher: " "
|
||||
[#]: url: " "
|
||||
|
||||
文档写作的 DevOps 指南
|
||||
======
|
||||
|
||||
将文档写作加入到 DevOps 的生命周期中
|
||||
![Typewriter with hands][1]
|
||||
|
||||
DevOps 正在挑战技术文档的规范，这在IT历史上是前所未有的。从自动化到提高交付速度，再到拆除瀑布式软件开发生命周期模型，这意味着业务和技术文档的理念需要做出巨大改变。
|
||||
|
||||
以下是DevOps对技术文档不同方面的影响。
|
||||
|
||||
### 技术作家的角色变化
|
||||
|
||||
技术作家必须适应 DevOps。好消息是，许多技术作家已经加入到开发团队中，并且由于拥有合作关系和不断增长的产品知识，这些技术作家很具优势。
|
||||
|
||||
但是如果一个技术作家习惯独立工作，并依赖于领域专家的草稿作为文档的基础，那么就需要做一些调整。
|
||||
|
||||
进行一些投资以确保文档和其他与项目有关的开发工作获得所需的工具、结构和支持。 从改变[技术作家聘用习惯][2]开始。以[DevOps 的速度][3]编写文档需要重新思考内容规划，并打破DevOps 团队和支持项目的技术作家之间长期存在的隔阂。
|
||||
|
||||
DevOps 使开发团队摆脱了传统文档实践的束缚。首先，文档[完成的定义][4]必须改变。一些企业的文化使技术作家成为软件开发的被动参与者。DevOps提出了新的要求--随着 DevOps 文化的转变，技术作家的角色也应发生变化。技术作家需要（且必须适应）DevOps 提供的透明度。他们必须融入 DevOps 团队。取决于组织如何塑造这个角色，将技术作家带入团队可能会带来技能上的挑战。
|
||||
|
||||
### 文档标准、方法和规格
|
||||
|
||||
虽然 DevOps 还没有影响到技术文档本身，但开源社区已经加强了对应用编程接口（API）文档的帮助质保，已经有不同规模的企业的 DevOps 团队正在使用这些文档。
|
||||
|
||||
用于记录 API 的开源规范和工具是个非常值得关注的领域。我想这是由于[谷歌文档季][5]的影响，使得一些专业的技术作家能够接触到开源项目，并解决最关键的文档类项目。
|
||||
|
||||
开源 API 属于 DevOps文档讨论。云原生应用集成需求的重要性正在上升。[OpenAPI 规范][6]--一个定义和记录API的开放标准--是在 DevOps 环境下 API 文档的良好资源。然而，该规范会导致文档的创建和更新过程变得很费时，这使其饱受批评。
|
||||
|
||||
曾经也有短暂尝试过创建[持续文档][7]，并且还有一个来自 CA（现在的Broadcom）的创建[DocOps][8]框架的运动。然而，DocOps 从来没有作为一个行业运动流行起来。
|
||||
|
||||
DevOps 文档标准的现状意味着 DevOps 团队（包括技术作家）需要在项目的最初阶段开始创建文档。要做到这一点，需要把文档作为一个敏捷故事和（同样重要的）管理期望来添加，并且把它与年度绩效评估放在一起执行。
|
||||
|
||||
### Documentation tools 文档工具
|
||||
|
||||
文档的编写应该以一种所有团队成员都可以使用的格式或平台在线进行。MediaWiki、DokuWiki、TikiWiki和其他[开源维基][9]为 DevOps 团队提供了一个编写和维护文档的中央仓库。
|
||||
|
||||
让团队选择他们的 wiki，就像让他们选择他们的其他持续集成/持续开发（CI/CD）工具链一样。开源维基强大之处在于其可扩展性。例如，DokuWiki包括一系列的扩展，你可以通过安装这些扩展来创建一个符合你的 DevOps 团队的创作要求的平台。
|
||||
|
||||
如果你有足够的野心来加强你的团队的编写和协作能力，[Nextcloud][10]（一个开源的云协作套件）是一个让你的 DevOps 团队上网并给他们提供编写文档所需工具的选择。
|
||||
|
||||
### DevOps 最佳实践
|
||||
|
||||
文档在 DevOps 转型中也发挥着作用。例如，组织从 DevOps 实现效率和流程增益的最佳实践的相关记录，这些信息太重要了，不能靠着 DevOps团中之间口口相传。如果你所在的组织有多个 DevOps 团队，那么文档就是统一的力量，它可以促进最佳实践的标准化，并设置了衡量代码质量的基准指标。。
|
||||
|
||||
一般情况下，开发人员承担了记录 DevOps 实践的工作。即使他们的组织有技术作家，他们也可能跨开发团队工作。因此，开发人员和系统管理员能够捕捉、记录和交流他们的最佳实践是很重要的。这里有一些朝正确的方向发展的提示：
|
||||
|
||||
* 提前花时间为 DevOps 最佳实践创建标准模板。不要陷入复制在线模板，采访利益相关者和团队来创建一个符合团队需求的模板。
|
||||
* 寻找一些方法进行信息收集，例如记录团队会议和使用聊天系统日志来作为文档的基础。
|
||||
* 建立一个用于发布最佳实践的 wiki。使用 wiki 可以跟踪编辑和更新。这样的平台可以帮助团队在最佳实践发生变化时进行更新和维护。
|
||||
|
||||
当在构建 CI/CD 工具链时记录依赖关系是非常明智的。尤其是当加入新的团队成员时，你会发现这些记录非常有用，另外当团队成员忘记一些事情时，这也是一种保险。
|
||||
|
||||
最后，自动化对 DevOps 利益相关者和从业者都很有吸引力。在自动化中断之前，一切都很有趣。拥有自动化运行手册、管理指南和其他内容的文档（并且是最新的）意味着无论何时发生故障，员工都可以让自动化重新工作。
|
||||
|
||||
### 最后一些想法
|
||||
|
||||
DevOps 对于技术文档来说是一个积极的因素。它将内容开发纳入DevOps生命周期，并打破组织文化中开发人员和技术作者之间的隔阂。没有技术作家的优势，团队就可以使用工具来加快文档创作的速度，以与DevOps的速度相匹配。
|
||||
|
||||
您的组织将如何把文档加入到 DevOps 生命周期？请在评论区分享您的经验。
|
||||
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
via: https://opensource.com/article/21/3/devops-documentation
|
||||
|
||||
作者：[Will Kelly][a]
|
||||
选题：[lujun9972][b]
|
||||
译者：[Veryzzj](https://github.com/Veryzzj)
|
||||
校对：[校对者ID](https://github.com/校对者ID)
|
||||
|
||||
本文由 [LCTT](https://github.com/LCTT/TranslateProject) 原创编译，[Linux中国](https://linux.cn/) 荣誉推出
|
||||
|
||||
[a]: https://opensource.com/users/willkelly
|
||||
[b]: https://github.com/lujun9972
|
||||
[1]: https://opensource.com/sites/default/files/styles/image-full-size/public/lead-images/typewriter-hands.jpg?itok=oPugBzgv "Typewriter with hands"
|
||||
[2]: https://opensource.com/article/19/11/hiring-technical-writers-devops
|
||||
[3]: https://searchitoperations.techtarget.com/opinion/Make-DevOps-documentation-an-integral-part-of-your-strategy?_ga=2.73253915.980148481.1610758264-908287796.1564772842
|
||||
[4]: https://www.agilealliance.org/glossary/definition-of-done
|
||||
[5]: https://developers.google.com/season-of-docs
|
||||
[6]: https://swagger.io/specification/
|
||||
[7]: https://devops.com/continuous-documentation
|
||||
[8]: https://www.cmswire.com/cms/information-management/the-importance-of-docops-in-the-new-era-of-business-027489.php
|
||||
[9]: https://opensource.com/article/20/7/sharepoint-alternative
|
||||
[10]: https://opensource.com/article/20/7/nextcloud
|
||||
Loading…
Reference in New Issue
Block a user