Podcast episode: Mike McKiernan at Red Hat on using Git Pre-commit to automate adding metadata to content files”

Diagrams help your readers understand. Chris Metz gives "A brief demonstration of Mermaid.js" – Write Open Source

This episode is a video demo, which you can see here on spotify or vimeo.   Chris Metz is a freelance solutions architect and tech writer with cloud and emerging technologies based in Danville, California, near the San Francisco Bay Area.  In "A brief demonstration of Mermaid.js," Chris  shows us how to use Mermaid.js to add diagrams to your documentation.  Chris recently added the Diagram Guide to the Kubernetes.io website, where he is a regular contributor. To me, this diagrams-as-code has several benefits: It separates the content of the diagrams from how they are presented, which means that all your diagrams have a consistent look. The search results will include your diagrams when you edit and search your docs. Writers and developers can directly create diagrams without using specialized tools or creating asset files that get lost. — Send in a voice message: https://podcasters.spotify.com/pod/show/write-open-source/message

1. Diagrams help your readers understand. Chris Metz gives "A brief demonstration of Mermaid.js" 06:06
2. Jim Angel, Infrastructure Cloud Consultant at Google, on how NOT getting a $1/hr raise launched his tech career 20:29
3. Tim Bannister on contributing to the Kubernetes.io documentation 11:59
4. Mike McKiernan at Red Hat tells us about using Git Commit to automate adding metadata to his content files 05:21

Transcript

Rolfe: I heard in a recent meeting that you were working on a script that’s going to insert information about the assemblies into the top of the module. Tell me how this came about: how did you start working on it?

Mike: So pre-commit is a system that’s sort of like a framework that’s been put together in Python, and it’s broadly applicable for anything related to Git. It’s not related to documentation. It’s okay for software development and may even be more popular with software development.

The upshot is that, uh, right after you run a Git add, and you add the modules or the files you want to put into the commit when you run git commit, it runs what are called these Git pre-commit hooks.

And, in this particular case, the pre-commit hook is just a Python program that receives a list of the files that are in the commit and can distinguish between the modules and the assemblies.

And then for any of the modules that are updated, if there are any modules to be updated in the commit, races through the repo, figures out the relationship between assemblies and all the modules, and then updates any modules you might have.

And, I mean, I don’t know if it’s apparent to the audience, but it’s a tedious task, and it’s the kind of thing that you definitely want to have software do for you.

Rolfe: How did the initial request from this come up?

Mike: I guess the initial request was that this was a task that we used to do for all Red Hat documentation – that’s my understanding – and then the requirement for writers to keep this information updated seemed to fall by the wayside due to the Modular Docs steering committee. And I definitely adopted that freedom to not update this information as soon as that was even hinted at.

And then, but we subsequently learned through team meetings that our DPM (Document Program Manager) was interested in continuing to have this information updated. And at that point, I guess it was really sort of just a selfish desire to get myself out of that business because, as I said, I really don’t have any interest in gathering that information, keeping it up to date. It’s just, again, the perfect job for a computer–a bad job for a human.

Rolfe: Yeah. So you were solving a problem for yourself and helping other people at the same time.

Mike: It’s very, yeah, it was definitely, uh, absolutely selfishly motivated. No argument there, whatsoever, but I guess just sort of in the spirit of, uh, collaboration, teamwork, caring about people I work with. And then part of it’s the red hat ethos of open source and sharing.

I just offered…I shared with the team my experience and offered to support anybody who was interested in following that path of using pre-commit to use that hook.

Rolfe: So where’s the project now?

Mike: https://github.com/mikemckiernan/module-used-by, I think, is the name of the repo, but certainly it’s easier to type in sort of, uh, write down. In terms of status, I believe I’m complete with it.

Rolfe: Thanks. Is there anything else that you’d like people to know about this project or any thoughts?

Mike: Uh, only that it’s pre-commit is one…So within pre-commit, if this doesn’t sell you on pre-commit, that’s fine. Um, but just as an awareness across the writing group and anyone else at Red Hat, pre-commit is a really awesome way to automate any kind of a check.

There is a really strong series of hooks that are related to markdown that can run linters on your markdown, that can reformat your markdown, and it really can help enforce consistency across the repo. And it’s very opinionated, and the benefit there is that, then there’s very little time spent amongst contributors over, sort of, these like tiny details about layout, things like that, that really are not super important for the end-user, right, and so it just, it, it cuts through those sort of disagreements.

Rolfe: Thank you. I really appreciate your taking the time, and we’ll talk again soon. Okay.

Mike: Very cool. Thanks, Rolfe. Have a good weekend.

Rolfe: You too. Have a good weekend. Bye.