aster.cloud aster.cloud
  • /
  • Platforms
    • Public Cloud
    • On-Premise
    • Hybrid Cloud
    • Data
  • Architecture
    • Design
    • Solutions
    • Enterprise
  • Engineering
    • Automation
    • Software Engineering
    • Project Management
    • DevOps
  • Programming
    • Learning
  • Tools
  • About
  • /
  • Platforms
    • Public Cloud
    • On-Premise
    • Hybrid Cloud
    • Data
  • Architecture
    • Design
    • Solutions
    • Enterprise
  • Engineering
    • Automation
    • Software Engineering
    • Project Management
    • DevOps
  • Programming
    • Learning
  • Tools
  • About
aster.cloud aster.cloud
  • /
  • Platforms
    • Public Cloud
    • On-Premise
    • Hybrid Cloud
    • Data
  • Architecture
    • Design
    • Solutions
    • Enterprise
  • Engineering
    • Automation
    • Software Engineering
    • Project Management
    • DevOps
  • Programming
    • Learning
  • Tools
  • About
  • Data
  • DevOps
  • Practices
  • Tools

A DevOps Guide To Documentation

  • Aelia Vita
  • July 6, 2021
  • 4 minute read

Bring your documentation writing into the DevOps lifecycle.

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.


Partner with aster.cloud
for your next big idea.
Let us know here.



From our partners:

CITI.IO :: Business. Institutions. Society. Global Political Economy.
CYBERPOGO.COM :: For the Arts, Sciences, and Technology.
DADAHACKS.COM :: Parenting For The Rest Of Us.
ZEDISTA.COM :: Entertainment. Sports. Culture. Escape.
TAKUMAKU.COM :: For The Hearth And Home.
ASTER.CLOUD :: From The Cloud And Beyond.
LIWAIWAI.COM :: Intelligence, Inside and Outside.
GLOBALCLOUDPLATFORMS.COM :: For The World's Computing Needs.
FIREGULAMAN.COM :: For The Fire In The Belly Of The Coder.
ASTERCASTER.COM :: Supra Astra. Beyond The Stars.
BARTDAY.COM :: Prosperity For Everyone.

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. Documentation at the speed of DevOps 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 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.

Read More  Ditching Google: The 3 Search Engines That Use AI To Give Results That Are Meaningful

 

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, 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—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 methodology. There was also a movement to create a DocOps 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 offer DevOps teams a central repository for authoring and maintaining documentation.

Read More  The Future Of Work Requires A More Human Approach To Security

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 (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.
Read More  Delegate Common Tasks With An Open Source Automation Tool

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.

This article is republished from opensource.com


For enquiries, product placements, sponsorships, and collaborations, connect with us at [email protected]. We'd love to hear from you!

Our humans need coffee too! Your support is highly appreciated, thank you!

Aelia Vita

Related Topics
  • API
  • DevOps lifecycle
  • Opensource
  • Programming
  • speed of DevOps
  • technical writers
You May Also Like
View Post
  • Data
  • Multi-Cloud
  • Platforms

Microsoft And Oracle Expand Partnership To Deliver Oracle Database Services On Oracle Cloud Infrastructure In Microsoft Azure

  • September 14, 2023
View Post
  • Data
  • Learning

Resources to Take Your Charts From Bland to Beautiful

  • September 6, 2023
View Post
  • Data
  • Platforms
  • Technology

Reimagine Data Analytics For The Era Of AI

  • August 30, 2023
View Post
  • Data
  • Platforms

IBM Introduces ‘Watsonx Your Business’

  • August 28, 2023
Automation
View Post
  • Automation
  • Platforms
  • Tools

Automate Your Data Warehouse Migration To BigQuery With New Data Migration Tool

  • August 24, 2023
View Post
  • Data
  • Research
  • Technology

Using Machine Learning To Help ZSL & Network Rail Monitor And Improve Biodiversity Near British Railways

  • August 20, 2023
Redis logo
View Post
  • Data
  • Platforms
  • Software Engineering

Redis 7.2 Sets New Standard For Developers To Harness The Power Of Real-Time Data

  • August 15, 2023
View Post
  • Data
  • Technology

IBM And The USTA Add Generative AI Commentary And AI Draw Analysis To The 2023 US Open Digital Platforms

  • August 15, 2023

Stay Connected!
LATEST
  • 1
    Combining AI With A Trusted Data Approach On IBM Power To Fuel Business Outcomes
    • September 21, 2023
  • 2
    Start Your Ubuntu Confidential VM With Intel® TDX On Google Cloud
    • September 20, 2023
  • Microsoft and Adobe 3
    Microsoft And Adobe Partner To Deliver Cost Savings And Business Benefits
    • September 20, 2023
  • 4
    Huawei Connect 2023: Accelerating Intelligence For Shared Success
    • September 20, 2023
  • 5
    Huawei Releases Data Center 2030, Leading Innovation and Development of New Data Centers
    • September 20, 2023
  • Penguin 6
    How To Find And Fix Broken Packages On Linux
    • September 19, 2023
  • Volkswagen 7
    Volkswagen Races Toward Next-Gen Automotive Manufacturing Leadership With Google Cloud And T-Systems
    • September 19, 2023
  • 8
    VMware Scales Multi-Cloud Security With Workforce Identity Federation
    • September 18, 2023
  • Intel Innovation 9
    Intel Innovation 2023
    • September 15, 2023
  • Private 10
    A Comeback For Private Clouds
    • September 14, 2023
about
Hello World!

We are aster.cloud. We’re created by programmers for programmers.

Our site aims to provide guides, programming tips, reviews, and interesting materials for tech people and those who want to learn in general.

We would like to hear from you.

If you have any feedback, enquiries, or sponsorship request, kindly reach out to us at:

[email protected]
Most Popular
  • 1
    Microsoft And Oracle Expand Partnership To Deliver Oracle Database Services On Oracle Cloud Infrastructure In Microsoft Azure
    • September 14, 2023
  • 2
    Real-Time Ubuntu Is Now Available In AWS Marketplace
    • September 12, 2023
  • 3
    IBM Brings Watsonx To ESPN Fantasy Football With New Waiver Grades And Trade Grades
    • September 13, 2023
  • 4
    NASA Shares Unidentified Anomalous Phenomena Independent Study Report
    • September 14, 2023
  • 5
    Introducing OpenAI Dublin
    • September 14, 2023
  • /
  • Technology
  • Tools
  • About
  • Contact Us

Input your search keywords and press Enter.