Duration	~1 hour
Audience	Writers et al
Host	Write The Docs
Event	https://md.engineer/wtd-dc

docs-as-code | Presentation

Context

How I got to present to WTD Kenya community

1. A WTD Member called me (referred by a mutual friend)
2. We talked about Technical writing as a career
3. Mentioned docs-as-code was a knowledge gap for him and others
4. I get introduced to WTD Kenya community
5. We schedule a date
6. Event is postponed (I had an unforeseen commitment)
7. Event is held on Aug 1 2023, at 7PM EAT

About Stan

Contact: md.engineer/contact
Web Profile: md.engineer
My writing: md.engineer/writing

Unfortunately, I couldn't get a great excerpt from the recording to share. The notes here will have to do 🙏

Software Engineering and Digital Products professional

• 7+ years professional experience
• Software Engineering
  • Full-Stack
  • Team Lead
  • DevOps
• Digital Products
  • Product Management
  • Content (Docs and UX writing)

Docs-as-code

Docs-as-code (by WTD WriteTheDocs)
Philosophy where documentation is treated as code
Documentation as Code (Docs as Code) refers to a philosophy that you should be writing documentation with the same tools as code

For purposes of this session I'll handle three main areas; Markdown as a format, Git for version control, and GitHub as the platform.

Table of Contents

• Content format - Markdown
• Version control - GIT
• Platform - GitHub
• Advanced

Markdown

Syntax and Tool

• Syntax - Great formatting syntax for web-writers

  • a plain text formatting syntax for web-writers that's:
    • easy to write
    • readable and publishable as-is (like plain text, without being marked up with tags or formatting instructions)
    • easily converts to structurally valid HTML
  • First time using Markdown?
    • Help
    • Tutorial
    • Guide
    • Use Dillinger to show common
  • Note:
    • Some editors/markdown processors support HTML and other extended syntax

• Tool - Tools that support MarkDown:

  • Dillinger
  • Docs to Markdown (Google Docs add-on)
  • Obsidian
  • Notion
  • Coda
  • Trello
  • Discord
  • Slack
  • Ghost
  • GitHub pages - Jekyll

  VS Code - Code editor (We'll use moving forward)

GIT

Version Control

• Version Control

  • A case for 'versions'
  • Use Google Docs to show versions
  • A case for 'version control' - tracking and managing changes
  • git - a tool for controlling version

  In-depth content about Git.

• git commits

  commit explained - You can play around, a time comes when you commit. git commit - commit a change/ version)

  Getting started (Atlassian Tutorial)
  VSCode inbuilt Source Control

  • git init
  • git add .
  • git commit -m <commit-message>
  • git log

  In-depth content about git commits.

• git branches

  branches explained - A tree grows as one trunk then at a point (commit), then a branch/ branches grow. But, in git, the branch can join the main branch/ trunk)

  A branch is a separate linear series of commits (oversimplified, at least that's usually the intention).

  • git checkout -b <branch-name> (check-out (as in a ) branch out)
  • Multiple branches
    • alias glogat (To show one-line commits with timestamps and a graph showing branching visually)

  In-depth content about Git branches.

• Tools:

  • GitHub desktop
  • VSCode (Source Control)

GITHUB

GitHub docs
GitHub Training Manual
Collaborating - (Atlassian Tutorial)

• Distributed Git

  • Remote Git repository - GitHub

    • Create repository on GitHub web

      Alternatively run gh repo create <repository-name> --public

      gh - GitHub CLI

  • PUSH and PULL explained

    • PUSH to GitHub
    • PULL to local

• PR - Pull Request

  • Request: "Please pull these changes into this branch"

  Alternative name: MR - Merge Request (on GitLab)

  • Request: "Please merge these changes into your branch"

Advanced

In my opinion, deliberate, slow explanation is needed to fully explain this.

I touched on these during the recording. Despite having more than 1 hour to cover it, I felt that time was still short and I rushed through it.

In retrospect, this section deserves another presentation should the team at WTD have me (for their community)

On Docs-as-code

• Fast facts about docs as code at GitLab
• CloudFlare's docs-as-code-approach
• docs-as-code article by opensource.com
• docs-as-code article by I'd Rather Be Writing
• docs-as-code article by grab's engineering team
• docs-as-code article by Nordic APIs
• https://www.docslikecode.com/
• Some common references and introductory content on Docs as Code

On Technical Docs

• https://diataxis.fr/ - A systematic approach to technical documentation authoring

On Markdown

• History Version 1.0.1 in 17 Dec 2004
• Standard variation - CommonMark
• Markdown is a lightweight | markup language for creating formatted text using a plain-text editor.
• It's both syntax and tool:
  • a plain text formatting syntax for web-writers that's:
    • easy to write
    • readable and publishable as-is (like plain text, without being marked up with tags or formatting instructions)
    • easily converts to structurally valid HTML
    • File extensions
      • .txt - plain text file
      • .md - markdown
      • .html - HTML (Standard markup language for documents designed to be displayed in a web browser. Defines the meaning and structure of web content)
  • a software tool, written in Perl, that converts the plain text formatting to HTML
    • Nowadays, a number of editors have the a markdown processor in-built
• Extended syntax
  • Highlights
  • StrikeThrough
  • Task Lists

On GIT

GIT is a free and open source distributed version control system

• Atomic commits
• Rebasing branches
  • Merge conflicts
• Others

On GitHub

• PR (Pull Requests)
  • PR tags
  • PR reviewers
  • PR checks
  • PR deploys
  • PR reviews with commits
  • PR - code sandbox
• Workflows
  • Draft (your branch)
  • In review (PR)
  • Published (main branch)
• Deployments
• Example of Workflows and Deployments using a Minimalistic SSG (Static Site Generator)
  • Repository with automated deploys
  • Deployment
• Writing on GitHub - Starter
• Writing on GitHub - Advanced