Ubuntu Server Gazette - Issue 3 - Document with a little help from my friends

Recap of the the Ubuntu Server guide history

As far as I can remember there always used to be a server guide helping users to set up services well and to understand more about their Ubuntu systems.

About a decade ago when I joined Canonical, that was still HTML based and maintained in bzr repositories. It feels dated now but represents the time it was created a few years earlier. There always have been community contributors, but never as much as we were hoping for. While I might do a disservice to the others, the one that clearly was around and awesome all the time was @dsmythies - worth a call out! The Ubuntu Server team did particularly well to continuously allocate time to ensure at least some items got tackled alongside each Ubuntu release. But despite all of that, Server just didn’t get the contributor traction that the Desktop-oriented Wiki got.

Then six years ago in 2019 that system was modernized to enhance the contribution process. The existing content was carried over to the Ubuntu Discourse instance. That allowed rendering to different formats (wiki style discourse, web-page, PDF), defining the style more independently to the content and – most importantly – allowed for better discussion around the content and wiki style editing. It also allowed us to unite the rendering style with other documentation that is created around Ubuntu. Furthermore, as a team we established triaging interactions in the same way we do for bugs via a daily rotation to ensure nothing would be lost or linger for too long.

In late 2022 the Server team got a Technical Author to help guide the documentation efforts in line with the vision set out by the Documentation Practice Lead at Canonical. As part of this, we also adopted the Diataxis model to provide greater clarity and structure in the documentation…

The Discourse approach improved interaction in regard to discussions, but did not yet increase contributions as much as we hoped. When discussing that with our community we found that for our audience, mostly being developers and server administrators, a Git + Read the Docs approach feels more natural. Thereby the next evolution happened in mid 2024, when we moved to such a setup. To the reader, this was non-disruptive as it still renders the same page, just from a different source. Discussions continued to be healthy now via the issue tracker, but we started to see more actual outside contributions – from single-word typo corrections to updates and additions to the content. Even internally, a git-based workflow felt liberating and we kicked things off with a 3 day virtual sprint fighting a lot of our documentation backlog (Fig 1, Jul 24).

Since then throughout the rest of 2024, community discussions and contributions ramped up gradually (Fig 1, Aug-Dec 24). Our hope that this would be appreciated and better received by our community was confirmed. But joining the CODA was the next step ahead.

What is CODA?

The Canonical Open Documentation Academy is a welcoming community made by (and for) people who care about documentation. It’s really a nexus -- a way for open source projects to connect with people who want to contribute but aren’t sure where to start.

For projects who need help with documentation, the CODA community can help to curate and shape issues in a way that they can be picked up and worked on by our growing community of volunteers. For our volunteers, it provides mentoring and other opportunities to share and develop skills in documentation, as well as a supportive onboarding into the world of open source.

Ubuntu Server Guide joins CODA

Immediately after the EOY shutdown, we signed up the Ubuntu Server documentation to the Canonical Open Documentation Academy.
Armed with a carefully curated list of issues from our team backlog (thanks @bryce !), the definition of our contributing guide, and some helpful insights from the rest of the CODA team, we took the plunge.

In just our first month, the number of community PRs submitted against our docs more than tripled (Fig 1, Jan 25) and continues to grow a lot ever since (Fig 1, Feb - Mar 25)! Our new contributors have provided us with a huge variety of submissions, as you can see in our new page highlighting the improvements our contributors have made. At the same time our Team itself also drives more changes and tasks than ever based on the very same engagement with the community.

Our community is currently working on building out a glossary of key Ubuntu Server terms, which also has a wikipedia-style hover-over functionality!

We are entering the era of a luxury problem to have, that of more (and sometimes rather complex!) contributions than what we can serve well in regard to review, verification and guidance. That made us adapt some of our 25.10 plans to allocate more time for it and might one day lead to the need for community co-maintainers.

And :innocent:you :smiling_imp:?

It does not matter if you want to help because you are kind or if you want to see us suffer under more contribution load because you are evil - both decisions in this matter of conscience lead to the same path: Please be welcome to contribute to the Ubuntu Server Guide.
If you have never contributed before but would like to, consider starting with the Documentation Academy -- the issues posted here are specifically tailored for people making their first ever contributions!

7 Likes

Oh my goodness!!! I had no idea things had changed so much. Thank you for the call out.

I still publish help.ubuntu.com and now realize that the server links and some descriptions are out of date. Some of the HTML links seem to redirect to the current locations, but the PDF links are obsolete and need to be updated. I’ll try to fix things in the next few days.

3 Likes

The serverguide related links and note on help.ubuntu.com have been updated.
Please let me know via here or via the related bug report if something is wrong or needs clarity or whatever.

Yeah, and if you do not know too many will not know - hence I wanted to give it another round of exposure :slight_smile:

They look good to me now, thank you @dsmythies