Writing in style 2.0
3 years ago we implemented a style guide on the Umbraco Documentation. The purpose of this style guide was to help contributors write not only good documentation but excellent documentation.
Along with the style guide, we also added a style linter to the GitHub repository where the documentation lives. This allowed us to set up some automation to check every incoming Pull Request against our defined guidelines.
If you want to learn more about how this all works, read Sofie's Docs Diary Vol. 16: Writing in style 😎 from 2019.
Over the past few months, we’ve picked up the style guide once more, revised what was there, and added a bunch of new guidelines to improve the readability of the Umbraco documentation even further.
The following guidelines have been added or revamped:
- Write shorter sentences
We now encourage you to keep your sentences below 25 words. Not always an easy task, I can tell you! But breaking tech-heavy and often complex information into smaller chunks helps to improve readability and the ability to understand the written. - Define acronyms on first use - NEW ✨
Working in the software industry we might take the definition of a lot of acronyms like common knowledge. OK, maybe ‘HTML’ and ‘CSS’ don’t need an introduction, but ‘CDN’, ‘CLI’, and ‘SSMS’ do! 🙈 We have implemented a guideline that will prompt you to define the acronym the first time it’s used in an article. - Spell Umbraco and Document Type correctly - NEW ✨
We want to ensure consistency between the Umbraco Documentation and the Umbraco products. This is why it’s important that features, product names, and other Umbraco-specific concepts are spelled correctly and use consistent casing. Is it ‘Doc Type’, ‘document-type’, or ‘Document Type’? In our guideline, we recommend using the latter 💪🏻
- Get the names, terms, and brands right
Some of these existed already, but we now have several guidelines to ensure that certain brand names and names of markup languages are written correctly. This includes writing ‘HTML’ instead of ‘html’ and remembering to capitalize the ‘T’ in ‘YouTube’. These might seem like small things, but in the big picture, they make a big difference to the overall perception of the Umbraco docs.
For Hacktoberfest we’ve asked for help with updating the Umbraco Documentation against all these new guidelines, and it has been a great success! Once we’ve had a minute to get an overview of all the things, we’ll make sure to share it with all of you ⭐
Adopting some Plumber docs
By now, you might be aware of the acquisition of the popular workflow extension called Plumber. If you don’t know yet, you can read about the acquisition here.
What does this mean for the Documentation team? The Documentation team, along with Nathan’s help and expertise, migrated the existing Plumber docs to Umbraco Documentation. The existing Plumber docs were further polished to fit the Umbraco Docs guidelines and style guides. Curious to look at the features and functionalities? You can find them in the Plumber documentation.
That’s not all! As a bonus, we have created a Umbraco Plumber playlist on the Umbraco Learning Base YouTube channel to help you get started with Plumber.
For now, you can check out the Umbraco Plumber Overview video below 🤩
Umbraco Learning Base Highlights
So, what has happened on the Umbraco Learning Base channel these last couple of months? Since the last blog post, we have released 22 new videos 🤯 covering everything from creating a multi-page form with Umbraco Forms to an overview of the new Umbraco Plumber product to using the LogViewer in the Umbraco backoffice.
If you follow the channel (and you definitely should!) you might have noticed that we’ve had a focus on creating new videos for Umbraco Forms. The product is evolving quickly, and we want to highlight that!
- We created a video tutorial on how you can create multi-page forms with Umbraco Forms
- We created a tutorial on how you can create a contact form using Umbraco Forms
We’ve also released a bunch of new videos in our “Did You Know..?” series, which are great for getting a quick peek at some of the many great features of Umbraco products. Check it out if you haven’t already. It’s great for binge-watching 😌🍿
To finish the update about Umbraco Learning Base we chose a winner for our giveaway some weeks ago and the lucky winner was presented with some awesome Umbraco SWAG 😁
Take a look at the video we made 😁 Congratz once more, and thanks to all who participated in the giveaway!
Before wrapping things up here, we want to share something very exciting with you.
A new platform has been chosen for the Umbraco Documentation and we have already started the migration. We plan to have the new platform ready for testing and feedback in the middle of November - perhaps even already next week!
Hopefully, we’ll be ready in time for publishing the Umbraco Documentation on the new platform along with the release of Umbraco 11 in December.
Oh, and remember to keep an eye out for the Hacktoberfest roundup blog post coming soon. It’s been such a great success yet again, and on the docs side of things, the readability has been improved on a ton of articles 👏🏻
And that’s a wrap 🎬
PS: Remember to subscribe to the Umbraco Learning Base YouTube channel 😉