Wow, what a month of Hacktoberfest! The Kong community showed up in a big way to improve one of the most essential aspects of Kong — our documentation (docs) website!
Earlier this year, I spent a lot of time working with our docs site code and content to get the Kong Hub launched and ended up as the volunteer docs site maintainer — at least until we hire a technical writing lead (we are hiring!). Here at Kong, we are moving fast, and we’re grateful for our strongest asset: our large and growing community of users and supporters!
As Hacktoberfest approached, that community was on my mind. I hoped we might get a few community contributions to improve the functionality and content of our docs site, so I spent some time in September and early October making sure our docs site repository was welcoming to contributors — most notably, I cleaned up our issues and open pull requests (PRs), and I labeled a number of issues “good first issue.”
As October proceeded, we started getting PRs, and they just kept coming and coming — wow, what a month it was! We had way, way, WAY more pull requests, active issues and authors in October 2018 than we’ve had any month since the Kong docs site went live more than three years ago. Fifty-nine PRs by 38 people — that’s a lot of hacking! Here is a selection of the terrific contributions received during Hacktoberfest:
Wait, What Version am I on?!
Long ago, we added a drop-down menu to our docs site to allow visitors to pick the version of Kong or Kong Enterprise they were using, but it was still hard to tell what version you had selected while looking at the menu. Josiah Dahl made a big improvement by adding a little blue indicator reminding you which version is currently selected. Thank you, Josiah!
Check out that awesome blue indicator bar!
Flipping a Table… of Contents!
A Table of Contents (ToC) at the top of a given documentation page can help a reader get a preview of what they’ll learn on a page and help them quickly reach the section relevant to them. Since the start of the Kong docs site, we had been adding ToCs to some pages “by hand.” Each ToC needed to be carefully coded to link to the headings within the page — if the headings changed, the ToC needed editing too. Adding ToCs to new pages was also a totally manual process.
We knew there was a better way, and the community came together to help us implement it.
First, Vladimir Jimenez (the author of the awesome Jekyll Pure Liquid Table of Contents) contributed a new feature that auto-generated a ToC for each page as the docs site was being built.
While working on that, we realized we really needed to upgrade our Markdown rendering engine from an old version of redcarpet to a modern version of the now-default kramdown engine. That upgrade was tackled by Vividh Chandna and added automatic handling of what would otherwise be duplicate — and broken — ToC links to headings with the same name.
Once we had automatic ToCs that rendered correctly, we needed to remove all the old “manual” ToCs and needed to adjust heading levels on existing pages to ensure the ToCs auto-generated correctly. I took care of those fixes in our recent doc versions so that our helpful community members didn’t need to do this tedious work, but I didn’t have time to fix ALL the older versions of Kong’s docs. Casper Freksen came to the rescue and updated 211 (!) different docs pages to correct their heading levels, thus allowing automatic ToCs to render correctly.
With ToCs now on every page, users have a reason to scroll from the bottom of the page back up to the top. Vinayak kindly added “Back to ToC” links that take the reader from the bottom of the page back up to the ToC.
Wow, what a team effort! Huge thank you’s to Vladimir, Vividh, Vinayak and Casper!
So Good, we had to say it twice Let’s Just Say it Once
The heading area of our docs site pages has evolved over the years and had accumulated some redundancies along the way. Ting Lew made a terrific contribution to refactor the page headers for clarity and simplicity, with a couple tweaks from our web developer, Adam Kuhn. Thank you!
Before: Redundancy everywhere!
After: So fresh and so clean!
Consistently Consistent
As our docs site has grown, we haven’t always kept our styling consistent. For example, we discovered that numbered lists looked different on different parts of our site:
Some numbered lists had special formatting, but some did not.
Daniel Martin Gonzalez made the numbered list styling consistent across the site! Thanks, Daniel!
Code or a Link…Why Not Both?!
Sometimes we hyperlink code-formatted text in the documentation – but our CSS styling didn’t render these code examples as links, so it wasn’t apparent you could click on them. Josiah Dahl came through once again with a fix that made it visually apparent that such code examples could be clicked by site visitors – thanks!!
Don’t Copy that Prompt!
When copy/pasting commands from the docs to a terminal session, it was previously easy to copy the command prompt $ mistakenly. Triple-clicking on the command would also select the $, thus forcing docs site users to carefully select the commands “by hand” or paste their copy, then remove the $ by hand.
Our own Darren Jennings fixed the problem for all code snippets that were marked as bash in the markdown files, but some snippets weren’t marked. Casper Freksen helped out again and added markers for all of our code snippets, clearing the way for Darren’s PR and allowing users to copy commands straight from the docs. Thank you, Casper!
Selecting the code no longer selects the prompt.
What…and When
We’ve been publishing changelogs for both Kong and Kong Enterprise for a long time, but for some reason, we weren’t including release dates in the Kong Enterprise changelog. Well, thanks to Alex Ashley, there are now dates on the enterprise changelogs! This improvement didn’t require any code changes, but determining the release dates for past Kong Enterprise versions took sleuthing — thanks for being a great detective, Alex!
Kong Nation to Kong Docs
Our active discussion forum, Kong Nation, is popular with Kong community members and Kong Inc. staff – and in many cases, questions in Kong Nation indicate the need to add information to Kong’s documentation. Community member Palash Nigam stepped up and added some detail about log levels that had previously only been explained in a Kong Nation post. I hope we see more of these contributions that bring Kong Nation and our docs site closer together to better help Kong users. Thanks, Palash!
Many Hands Make Light Work
What an incredible month of collaboration and contribution Hacktoberfest 2018 was for the Kong community. The Kong docs site benefits all our potential, current and future users, and contributions to improving it are welcome at any time, not just during October.
I look forward to all the great things to come from our community as together we make Kong better every day.
The post Holy Hacktoberfest! The Kong Community Delivers appeared first on KongHQ.