Goal

On the Open Documentation Academy website, add an article containing both the video ODH-015: Documentation as code, done by Robert Kratky, and a concise summary of the video.

Context

Some great presentations and discussions have occurred during CODA's Community Hour. Sadly, people may have little time or energy, and they might not listen to a 30-minute video even if the topic could interest them.

Reasons for making a concise summary of the video:

• Make the video’s information accessible to more people.
• Make the video’s information easy to skim through. Key information could be highlighted.
• For learning purposes, anyone can quickly review this summary at any time to refresh their knowledge.
• The video is available for anyone wanting to deep-dive into the topic. The article may invite more people to listen to it.

Advices

Where do you add your document in the Information Architecture of the website?

The document could be added to > Writing resources > Explanation.

Structure

Ideally, each article should follow the same structure. The first contributor can define a template to be followed by the other contributors.

My proposal: (feel free to improve it)

• Title (which is the same as the video for findability)
• Video
• Summary

My own notes

Note: These are my personal notes for my own learning. They can absolutely be improved. Don’t hesitate to use them if you want to.

What does “Docs as code” mean?

Writing, testing, publishing, and maintaining documentation using the same tools developers use for software code.
Goals: content authoring (text editor), formatting (markup languages), version control (git) , issue tracking (JIRA), testing, validation, publishing, etc.

Benefits for dev teams

• Dev can contribute or review easily the documentation
• They consider it a part of the project more easily
• Documentation will be integrated in the product planning / in the definition of done
• Documentation is included in the project workflow
• Sense of common responsibility

Benefits for organizations or projects

• Easy switch to different formats and tools
• Tighter collaboration between teams
• Efficiency
• Aligning releases with publishing

Challenges for technical authors and devs

• Can be challenging because there is a steep learning curve
• Resistance from devs, documentation slow down the “done”
• Corrections are more visible

Transcription tool

You can listen to the video yourself and take notes, or you can also use a tool to transcribe the audio to text. I like this transcription tool but feel free to use any of the ones you like!

Additional idea

Some very interesting topics are sometimes discussed during the time for questions that happens after the presentation. Feel free to include any questions and responses you think are useful.