This is part of an occasional series of blogs about PostgreSQL commitfest patches. Look at the series intro which also lists some ground rules and expectations for what to expect in my thoughts below. 🐘
| Patch title and thread: | Create visible links for HTML elements that have an id to make them discoverable via the web interface |
| Commitfest at time of review: | 2023-03 |
| Status at time of review: | Waiting on Author |
As I said in the intro to this occasional series, writing about PostgreSQL patches forces me to stay engaged. I’m not the most technical contributor in the PostgreSQL space by any means so every bit of conversation and discussion I can read just helps me level up that much more.
Instead, I often focus on the usability issues as I talk or teach about PostgreSQL because that’s usually where my struggles are. “I wish things would work this way! I wonder if anyone has thought about that?” And sure enough, almost every time I think something like that I find discussion somewhere about how to improve the feature or the challenges that have prevented additional changes.
I still can’t believe how amazing it is that this is all just out there for us to learn from.
Anyway, I digress.
While there are a few other patches I’ve started to follow and write about (more to come soon), a quick succession of events today made me want to jump in and get a quick post out to highlight how efficient this community is at helping each other.
Documentation Usability
If you’ve been around PostgreSQL for any amount of time, you probably know that the PostgreSQL developers and community are very proud of the documentation (they should be!) but that it’s also been a source of frustration to many, particularly those with less experience. In fact, in the 2022 State of PostgreSQL survey, documentation was both the most “go-to” source for information and one of the most commented on things that could be improved.
There is so much good, deep, technical documentation content. Unfortunately, following through and intuitively connecting all the sections doesn’t always make sense. In other places, there are essential bits of wisdom “hidden” inside of callout (TIP/NOTE) boxes which are easy to miss. Code examples are another area that are usually helpful and to the point, but a bit light on detail in more complex areas.
But that’s not what this short post is about. Honestly, the overall improvement of the docs is pretty amazing over the last couple of years. The community and contributors has stepped with their efforts and the overall team has worked hard to act on usability suggestions. 👏
Linking to Documentation
That said, linking to various sections and callouts in PostgreSQL documentation has never been easy. A few releases ago (I’m not completely sure when), there was a lot of effort to ensure that most sections had ID tags in the generated HTML so that it was possible to link to specific sections, just not easy.
Because I’m doing more PostgreSQL presentations lately, I’ve noticed it more when I want to put links to specific sections for a slide deck or to share on social media. Earlier this week I was at it again and finally decided to ask on Twitter what other PostgreSQL users do.
The responses were super helpful, pointing me to a browser extension that will quickly display hidden ID tags on a page and help you get the URL with anchors. But then, another user directed me to a current commitfest entry that is directly trying to address this issue.
This patch does two things, mentioned in this message of the thread:
- Create a hover effect link next to hidden ID areas (like sections on a page)
- Emit a build warning when there is a section without an ID
🔥🔥🔥
I know that might seem small and not really worth a blog post (I think it is!) but the bigger point for me is this.
I asked if others had a solution or if anyone had considered making docs better. Within a few hours, I had multiple responses to solve my current problem (browser extension) and a link to a current patch and conversation around the best way to implement this in documentation.
That’s really freaking cool, folks! 😎
Documentation Patch Status
The patch made quick progress in January and February, but some late conversation around the best, “right” way to apply the patch through the documentation system has put the patch on hold for a bit. I have no experience with Docbook previously, although I have read through the PostgreSQL documentation page for it. Maybe this will be the thing that finally prompts me to get docs building locally on my machine.
If you have the skills or experience to contribute to the patch, I think you’d be surprised how much of a usability impact this would have over the long haul!