Docs-as-code: Writing, Publishing, & Maintaining Documentation for Your Projects
- Published on Oct 1, 2020
Let's learn about docs-as-code as an approach to writing software documentation - and then see it in action! In this crash course, we'll go through a standard docs-as-code setup: host your project and documentation source code on GitHub, write documentation in Markdown from your local dev environment and deploy the Hugo-generated doc site to GitHub pages to accompany your project. A template will be made available as a GitHub repository and shared during the session. This workshop is aimed at developers, but non-developers who do or intend to work closely with developer teams such as software technical writers, developer advocates, or support engineers may gain from this course as well.
This will be a hands-on event, with an intro talk/section related to Kat's talk at the Summer Suncoast Developer Conference talk.
- Do attendees need a laptop? Yes
- Do attendees need to have certain programs? A text editor such as Visual Studio Code, git, a GitHub account, Hugo (doing the QuickStart tutorial, gohugo.io/getting-started/qui... , is highly recommended)
- Do attendees need previous experience? How much? Familiarity with basic git workflows (e.g. forking a repository, using the ‘commit’ command, opening a pull request) will be extremely helpful.
- Knowledge of Markdown is recommended but not required.
I. Intro lecture/discussion on docs-as-code (20-30 min)
-What is "docs-as-code?"
-How do you implement a docs-as-code system?
-Who uses docs-as-code?
-Are there pros and cons to such a system?
- Set up a local dev environment by creating a new Hugo project within the boilerplate app
- Configure Hugo site to be deployed on GitHub pages
- Simple git workflow for updating and deploying app documentation
About our Speaker:
Kat Batuigas is a Developer Relations Content Specialist at Crunchy Data, an enterprise PostgreSQL company, where she creates developer-focused content for PostgreSQL users. She wrote and managed documentation for the initial release of our Crunchy Spatial offering, and before joining Crunchy Data she wrote and managed documentation for Technolutions Slate, a leading platform for higher education admissions and enrollment management.