veyepar: Building Docs like Code: Continuous Integration for Documentation

Author(s):	Mason Egger
Location	Cartoon 2
Date	jul Sat 27	Days Raw Files
Start	15:45	First Raw Start	15:31
Duration	0:30:0	Offset	0:13:36
End	16:15	Last Raw End	16:31
Chapters	00:00 0:16:02
Total cuts_time	25 min.

https://www.pyohio.org/2019/presentations/109
raw-playlist raw-mp4-playlist encoded-files-playlist host archive tweet mp4 svg png

assets release.pdf Building_Docs_like_Code_Continuous_Integration_for_Documentation_2.json
logs
Admin: episode episode list cut list raw files day marks day marks day image_files

State:

Locked:

clear this to unlock

Locked by:

user/process that locked.

Start:

initially scheduled time from master, adjusted to match reality

Duration:

length in hh:mm:ss

Name:

Video Title (shows in video search results)

Emails:

email(s) of the presenter(s)

Released:

has someone authorised pubication

Normalise:

Channelcopy:

m=mono, 01=copy left to right, 10=right to left, 00=ignore.

Thumbnail:

filename.png

Description:

markdown

It is common for developers to overlook the documentation of their works. They are either on a time crunch, lack the proper tooling, or simply just forget to create and update the documentation. Whatever the cause behind this, it is not a proper excuse for not keeping the documentation up to date. However, for all our development processes there are few as neglected as the documentation process. Documentation should be treated as important as the code that makes up the project. In this talk we'll take a look at current documentation processes and discuss moving the documentation into the code. With modern documentation tools such as MkDocs and Sphinx, both of which are Python powered tools, and Continuous Integration tools we can now include docs in the commit. They can be reviewed in code reviews, built and versioned in a CI tool, and even tested for things such as correct code examples and broken links. This is the process that the developer knows, understands, and enjoys. I introduced a team to this exact workflow and a working pipeline; all they had to do was keep the documentation up to date. This team currently has some of the most up to date documentation in a company of near two thousand engineers, and they never complain about writing/updating documentation. It’s just part of the workflow.

Project documentation is easy to neglect. Keep your docs inside your source repo and learn how to automatically build and publish beautiful docs on every commit. Viewers will leave with a new mindset on how to handle documentation, tooling for this process, and an easy-to-implement method to achieve this.

Comment:

production notes