Diagrams-as-code for Kubernetes.io

Mermaid is a Javascript-based diagramming and charting tool that uses Markdown-inspired text definitions and a renderer to create and modify complex diagrams. The main purpose of Mermaid is to help documentation catch up with development.

https://github.com/mermaid-js/mermaid

In my recent interview with Tim Bannister, Tim encouraged contributors to create more diagrams for the Kubernetes docs based on the new diagram guide that chrismetz09 created in December 2021.

Notably, this guide shows how to code diagrams using mermaid.js in a live editor!

“Mermaid lets you create diagrams and visualizations using text and code.“

This notion of diagrams-as-code has tremendous appeal for me! To illustrate why, let me tell you a quick story.

A few years back, I enlisted the help of THE primary graphic designer where I worked to create an information-rich diagram for some product documentation. Because of her talent and organization’s size, she was very much in demand. Using specialized tools, she designed a beautiful and informative diagram and exported it to a graphics file, which I published. A few weeks after publication, the software engineering team made a software change, and just like that, the diagram became outdated!

That approach was much better than the ad-hoc approach that had preceded. At least now, our diagrams were expertly designed, correctly branded, and consistent across all our products.

Unfortunately, that new approach could not be scaled up to meet the customer demand for properly-illustrated documentation, which I estimate at a minimum of 5000 new or updated diagrams per year. I arrived at this figure by estimating ten-plus diagrams per product, times fifty-plus products, times ten-plus additions/updates per product per year. (10+ x 50+ x 10+ = 5000+)

With that backdrop, the benefits of having diagrams-as-code seem significant:

  • Unlimited contributors can create and maintain diagrams using free and open-source software.
  • Teams can store and manage the code for diagrams alongside the documentation source.
  • The tooling separates content from presentation to give all diagrams a consistent look and feel.

Moreover, having source code for diagrams makes it is easier to search for specific terms when updating diagrams and conducting peer reviews.

I think it would make sense to give this new approach a try.

Write Open Source podcast with Tim Bannister, CNCF Top Documentarian, on contributing to the Kubernetes.io documentation

To see the video podcast, open this episode in the Spotify app.

To get the podcast on your favorite podcast listening app, visit https://anchor.fm/write-open-source/episodes/Tim-Bannister-on-contributing-to-the-Kubernetes-io-documentation-e1c3pdi

Podcast summary

  • Tim Bannister is a Consultant at The Scale Factory, London, England.
  • Tim is also a technical lead for the Kubernetes’ documentation special interest group (SIG), which looks after the https://kubernetes.io/ website and documentation.
  • Tim briefly describes the role of chairs and technical leads in the governance of the documentation SIG.
    • The docs SIG is a great way for newcomers to become involved with the organization.
    • You can contribute in a variety of ways, such as:
    • Being a new user a super-power because you can see the content with fresh eyes and identify areas to improve.
  • The Cloud Native Computing Foundation (CNCF) named Tim as the 2021 Community Award Winner for Top Documentarian!

Top Documentarian: This award recognizes excellence in documentation contributions to CNCF and its projects. Excellent technical documentation is one of the best ways projects can lower the barrier to contribution. CNCF staff selected the Top Documentarian and are happy to present the award to:
Tim Bannister – Tim is a contributor to Kubernetes and other projects and is the technical lead for the documentation SIG, establishing new subprojects, decommissioning existing subprojects, and resolving cross-subproject technical issues and decisions.

https://www.cncf.io/announcements/2021/10/15/cloud-native-computing-foundation-announces-2021-community-awards-winners/

To get updates, click Follow

To get updates when I post new content here, please click Follow in the lower right corner.

Note: I use Jetpack to handle followers/subscribers. Jetpack doesn’t allow anyone to export contact this information, so you don’t have to worry about anyone misusing it.

Git: How to finish a PR for someone who is away on vacation

In this video, I demonstrate the following procedure using a colleague’s PR as an example.

How to get a copy of someone else’s pull request from Rolfe Dlugy-Hegwer on Vimeo.

Suppose you work with someone who is away for the Thanksgiving or Christmas holidays. What if you need to make changes to their pull request and get them merged before they return?

Prerequisites

You and your colleague both have forks of the same upstream repo.

You have already cloned your fork of the repo to your local machine and set up the upstream remote.

Procedure

Change to your repo directory. For example, enter:

$ cd openshift-docs

Add a remote that points to your colleague’s fork of the repo, as shown in the video. You go to GitHub, find your colleague’s PR, go to their fork, copy the URL of their fork, and paste it into the following command. Also name the remote you’re creating. This name can be an arbitrary string, but I recommend using the person’s first name. 

$ git remote add <remote-name> <url-of-their-fork>

For example, enter:

$ git remote add roberto git@github.com:bob007/openshift-docs.git

Create a working branch:

$ git status
$ git checkout -b <working-branch-name>

For example, enter:

$ git status
$ git checkout -b  xyz-456

On GitHub, return to the PR, copy the name of the other user’s working branch, and paste it into the following command:

$ git pull <remote-name> <remote-branch>

For example, enter:

$ git pull roberto abc-123

Git displays a commit message, usually in vi, that says something about the merge you just performed. In vi, you can save this commit message by pressing the Esc, :, w, and q keys.

In your local working branch, open one of the files you know your colleague changed in their PR. If you’ve done everything correctly, you should be able to see changes from their PR in your local working branch.

Make your changes to the content.

When you’re ready, push the changes by entering:

$ git push origin HEAD

Create a pull request for your working branch on GitHub by visiting the remote URL shown in the command output from the previous command. Right-click the URL and select open. For example:

remote: Create a pull request for 'xyz-456' on GitHub by visiting:
remote:      https://github.com/yourusername/openshift-docs/pull/new/xyz-456

Additional resources

https://stackoverflow.com/questions/21255057/how-to-fetch-someone-elses-pull-request-to-fix-it

Video: How to use Vale on the command line

How to use Vale on the command line from Rolfe Dlugy-Hegwer on Vimeo.

NOTE: This is a silent video without narration. For the best viewing experience, maximize the screen and set the video quality to 720p.

Here, using the Linux CLI shell prompt, I show you how to:

Check out your working branch by using git.

  • Run the Vale style linter on a specific asciidoc file with no options, so that you can see all the suggestions and errors from Red Hat style.
  • Run Vale again with the –minAlertLevel option to display errors only.
  • Get the line number from each error message to find and fix a handful of errors in the asciidoc file.

For more information, see:

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

Tim Bannister on contributing to the Kubernetes.io documentation – Write Open Source

Tim Bannister is a technical lead for the Kubernetes.io documentation special interest group and a consultant at The Scale Factory. Here he talks about contributing to the Kubernetes.io documentation and joining the documentation special interest group (SIG). For Podcast notes, visit https://rolfe.blog/2021/12/23/podcast-episode-tim-bannister-on-contributing-to-the-kubernetes-io-documentation/ — Send in a voice message: https://anchor.fm/write-open-source/message
  1. Tim Bannister on contributing to the Kubernetes.io documentation
  2. Mike McKiernan at Red Hat tells us about using Git Commit to automate adding metadata to his content files

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.

I’m going to try making a podcast

I spend a lot of time thinking about the nature of my profession and the people I work with. Now, I’ve created a podcast so I have an excuse to talk to those people, ask all sorts of questions, and share interesting parts of the work!

Write Open Source is going to be a behind-the-scenes podcast for and about the technical writers and other experts who document open-source software. We hear about special projects, overcoming challenges, and learning new methods.

To create the podcast, I chose anchor.fm from Spotify. It simplifies the workflow of creating, producing, and distributing your podcast to all the major platforms, for free, from one simple mobile app.

I’m not sure I’ll publish regularly: I tend to “go silent” as I approach major work deadlines. On the upside, my interest in and involvement with the subject is evergreen, so I don’t expect to “podfade” out of existence. The main question in my mind is whether I’ll be able to get other tech writers, who are notoriously introverted, to speak on the record about their work. I have a feeling the audio format will make this easier than, say, trying to make a video series on the same topic. We’ll see how it goes.

Disabled Parents and Starting a Business: A Few Essential Tips

I’m publishing the following post on behalf of Ed Carter, a retired financial planner and the founder of ablefutures.org. Ed offer tools, original articles, and other resources that will provide helpful financial information to members of the disabled community.  Ed says, “Many people are unaware of just how many options they have when it comes to financial assistance and planning, so it’s an honor to offer my experience and change people’s lives for the better.”

One in four American adults has a disability. Many of those with disabilities are parents who need a reliable income source despite having work restrictions. One option many disabled parents turn to is starting their own business. While the idea of starting a small business may seem daunting at first, using the tips below can help you get your new endeavor up and running.

Look for Grants

There are various grants and other funding opportunities available for disabled people. However, these funding sources may change quickly because they’re often offered on a first-come, first-served basis and close when funds are no longer available. You can keep up to date with current grant information by regularly checking the following websites:

You can also apply for a small business loan if grant funding isn’t enough. There are several types of loans designed for small businesses.

Start an LLC

Starting an LLC is an excellent choice for disabled parents looking to get their own business up and running. LLC stands for limited liability company, and it’s one way you can register your business. An LLC offers multiple benefits, including:

  • Greater flexibility when compared to alternatives
  • Limited personal liability
  • Tax advantages
  • Less paperwork
  • Increased credibility

Using a lawyer to form your LLC can be costly. You can save money by filing the paperwork yourself or using Zenbusiness, a formation service. Since each state has its own regulations on forming an LLC, it’s essential to research your area’s specific laws ahead of time.

Understand How to Hire In-House Staff

Hiring your first few employees can seem like an overwhelming task. The most important thing to understand is that you shouldn’t feel pressured to hire quickly. It’s worth waiting for the right employee, even if it takes weeks or months to fill the position. To ensure someone is the right fit, ask the following questions during the interview process to get a feel for each candidate:

  • How many years of experience do you have in this field?
  • Why do you want this job?
  • What are your greatest strengths?
  • What is your greatest weakness?
  • Do you have any certifications, degrees, or on-the-job training that applies to this position?

You should also ask questions that apply to your specific industry and the available position during the interview process. At the end of every interview, ask if the candidate has any questions for you. Generally, you want someone to ask at least one question. This shows they’re interested in learning about the position and your business.

Outsource Where Applicable

It isn’t always financially prudent to hire an in-house team member, but you may not have the necessary skills to perform a task your business requires. At times like these, outsourcing becomes the most viable option. To choose whether to outsource or hire an in-house team member, ask yourself two essential questions:

  • Does this position have 20+ hours of steady work available each week?
  • Does outsourcing or hiring in-house make more financial sense?

Applying These Tips

Starting a business is an excellent option for disabled parents. Applying the above tips can make the process smoother by helping you find funding, choose a business structure, understand how to hire staff, and decide when outsourcing makes more sense. 

Image via Pexels