Sofie's Docs Diary Vol. 16: Writing in style 😎

The Documentation Style Guide

So many things to cover today, so I’d better jump right in:

In my blog post back in August, I mentioned that we’re working on pimping up the Documentation. Well, not exactly “Pimp my Ride”-style, but close!

We call it: “Writing docs in style” 😏 .. or, that’s at least what I call it!

Okay, this might require an explanation.

Style guide, Vale and Github

To ensure readability on every article in the Umbraco Documentation we’ve set up and implemented a style guide. Currently, it only has a few rules, such as “Don’t write sentences longer than 40 words” and “Always start list items with a capital letter”. 

We’ve set up the rules using an automatic style linter called Vale. As with the rest of the Documentation, the style guide is open-source, and you’re more than welcome to contribute and suggest more style rules!

So, style guidelines are great and all that, but how do we actually make sure that they are followed? 🤔

I’m glad you asked!

Every time a PR is made to the Umbraco Documentation a Github bot will run through the article(s) and check everything. If some of the checks fail, it will tell you the exact line in the article that you’ll need to revisit. If everything looks good, you’ll get a green check-mark and even a fun little gif.

These checks are all thanks to our very own Warren Buckley (@warrenbuckley) who made a Github bot that runs these checks. 

Can you publish something without following the tips from the style-guide bot? Yes, but we highly encourage that you do follow the tips. The reason why we’ve added the style guide is not only to help you in your writing process, it is also to help make the Documentation easier to read and understand for everyone. So it really is an overall win-win for both you and the many future readers of your helpful words.

Want to know more about this Style guide? We’ve written an article for the Documentation where you can learn more about the different rules and how you can run and install Vale on your own machine.

What else is new?

.. other than the style guide, of course.

Well, as you might know, Hacktoberfest is currently in progress. We’ve had so many great contributions already and they just keep coming!

One of our goals for joining Hacktoberfest again this year is to get some help verifying our Umbraco 7 documentation for Umbraco 8. So far, it’s been a smashing success! 🎉

More than 30 articles have been verified and updated for Umbraco 8 just this month - and it’s only October 21st 🤯

And on top of that, many grammar fixes and minor typos have been solved as well! I can’t wait to see the final result of Hacktoberfest when it’s over in a couple of weeks.

Here are a few highlights from the past months of Documentation:

Working with Record Data in Umbraco Forms

Our very own Bjarke Berg (@BjarkeBerg) has updated our Documentation about how to work with Record Data in Umbraco Forms. He’s versioned the article, which means there’s one for Umbraco 8 and one for Umbraco 7 💪

The Umbraco API

How to work with the web API in Umbraco has changed a bit from Umbraco 7 to Umbraco 8, and, of course, that means that the Documentation should also be changed a bit. This is only one of the many things that Carole Rennie Logan (@crgrieve) has helped with this month. She updated the article while she had to do some testing with it anyways 👏 Thanks!

Models Builder: Builder Modes

In this article, there’s a section about how to work with the API Models. Anders Bjerner (@abjerner) has given this particular section an update and added a bunch more details to how it works. Definitely make sure to check it out if you've been using API Models already, or if it’s something you’re planning on doing!

Other articles that have gotten a “touch-up”:

• Umbraco Cloud: Databases - Restructured into multiple pages, instead of one long article
• Web.Config - Versioned for Umbraco 8
• IoC/Dependency injection - Updated for Umbraco 8

Alright, I better stop here! I think you get the gist by now - A lot of great things keeps happening on the Documentation repository 😄

“Docs or it didn’t happen!”

… am I right? 😉

Now, this final thing I want to share with you today is something I’ve been really excited to share.

Back in September Umbraco sponsored a Write the Docs conference, and Jesper and I went there as representatives 🤩

Write the Docs is a 3 day conference in Prague which is being held every year. The conference consist of 1 day of writing and 2 days of talks, sessions and unconferences (kinda similar to the concept of Open Spaces you might know from Codegarden).

 

It was a great conference! We met a lot of super nice people, heard a lot of very interesting talks and joined in on some inspiring unconferences.

Oh, and Jesper did a lightning talk about our new style guide and the Github bot we use for it 👏

 

All in all, a very good experience, and I hope I get to attend the conference again next year 🤞

The Numbers

Okay, so this is the final-final thing for today: The mandatory look at how the Documentation numbers look compared to my last blog post - which is exactly 2 months ago today.

And you know what? They look amazing!

Yeah, yeah, I say that every time - I know, but this time.. I’ll let the numbers speak for themselves:

 

Right? 104 PRs merged in 2 months. That’s pretty neat!

We’re a bit more than halfway through Hacktoberfest by now, and we’ve already received more than 100 PRs from 51 different people - half of these are even brand new contributors to Umbraco 🤩

If you haven’t already, be sure to head on over to the Umbraco Documentation Issue tracker and see if there’s something you can pitch in on in order to improve documentation for everyone and, of course,  secure your Umbraco Hacktoberfest swag for this year.

That’s all for now.

Until next time... oh, and Happy Halloween 🎃

// Sofie