Sofie's Docs Diary Vol. 24 - Platforms, a new major, and more code samples!

Hello 2021 👋

A new year has started and we have already been cooking up a lot of exciting stuff on the documentation side of things.

In my final blog post of 2020, I gave you a little sneak-peek into what this year has in store for the Umbraco Documentation - both in written form and the visual kind 🎬

OK, as usual, I’ll be covering quite a lot, so let’s get started, shall we?

Here’s what’s on the menu today:

• Umbraco Documentation 2.0
• Let’s document the next Umbraco major!
• The Curators and the “Interns”
• Did someone say samples!?
• Numbers!

 

Umbraco Documentation 2.0

Now, to kick off 2021 properly, I’m going to talk to you a bit about how we’re currently investigating options for moving the documentation to an entirely new platform. We want to define how we want the Umbraco Documentation to be and look like in the future. 

Now, what does this mean exactly? Are we looking for a new platform for the docs?

Well, both yes and no. There’s actually a lot more to it than just picking a platform. Instead of looking at what the specific platforms have to offer, we’re zooming out a bit and looking at what kind of features we actually want and need. Our main goal is to serve all of our customers, users, and readers - well, that’s all of you! - with the best possible documentation experience we can and to do that, we need a kick-ass, umbazing, accessible, and intuitive platform!

Sounds easy enough, right? 😉

The “Documentation Platform Taskforce” currently consists of 7 Umbraco HQ members, all from different departments and with different perspectives on our products and to our customers. Some have a ton of experience with both Umbraco CMS, the documentation, and the community and some are very new to Umbraco and the products but have a lot of experience with working with customers.

A virtual whiteboard with virtual posters - we have to improvise with the collaboration techniques now that everything is moved online, right? 😉

Even though the group has a pretty substantial pool of knowledge and experience, we’re in no way a “fixed group”. We will be pulling on some expertise knowledge within Umbraco HQ, within the community, and within our growing pool of partners. We want to include our users in this process, as who better to help improve the user experience than the users themselves?!

Now, just a quick disclaimer here: It’s all about the platform! Of course, there will be some overlap with the content as well, but the primary focus here is the platform and what kind of features and functionality this platform needs, in order for us to be able to serve you the best content.

Here’s a few examples of the things we’ll be researching:

• Options for enabling user-feedback on the content
• Features to ensure that our docs are inclusive and accessible to all
• Tools that support writing docs for multiple versions of a product
• … and so much more!

It’s a super exciting and very inspiring process, and even though the Our platform is currently doing a great job of serving all of our documentation, I have no doubt that with the right tools, we can make the experience so much better!

 

Let’s document the next Umbraco major!

Yes! Something almost as exciting as a new documentation platform is the next major version of Umbraco which is releasing later this year. Big, big changes are included in this version. Well, we’re actually completely changing out most of the underlying infrastructure.

Now, that of course means that we will have our work cut out for us in terms of documenting all these new cool changes, updates, and features. We’ve already started the planning process - we’ve actually been in a planning phase around this for several months already! 

In my blog post back in December, I mentioned how we’ve created a separate repository for the documentation for the next Umbraco major version. The repository can be found here: Umbraco/UmbracoCMSDocs.

The new repository for documenting the next Umbraco Major 🎉

In the new repository, we’ve set up a very flat structure in which every article, with the exception of tutorials, goes into an “Articles” folder divided into all topics. The main idea with doing it like this is that it should be easier to search the articles and find exactly what you’re looking for when visiting the Umbraco docs.

Please do keep in mind though that this is all still a work in progress. We’re still working on mapping out how this will all look and take form in a new structure and possibly also on a new platform. 

For now, the flat structure will make it easier than ever to contribute to the docs. When you want to write or update an article for the next Umbraco major, you simply add a new folder under the “Articles” folder, add a new Markdown file, and start writing! No need to go investigate where a new piece of content would fit in a large structure - leave the curating to the Documentation Curators and you can focus on writing up some awesome docs! 😁

You’ll find more details about the workflow and recommended process in the README file on the repository, and if you have any questions at all, please do not hesitate to get in touch with us and we’ll be more than happy to help you out.

 

The Curators and the “Interns”

Has it already been a year? 🤯

Yes. Yes, it has. Busra and Sophie have been “interns” on the Documentation Curators team for a whole year by now. It’s been absolutely great to have them on the team. They provided a lot of new energy to the work we do and they contributed to some of the various projects we’ve been working on as well. Primarily the restructuring of the “Getting Started” section!

So, what happens now?

I’m very excited to tell you that both Busra and Sophie are staying on the team 🎉 We’re also upgrading their title, so instead of them being “interns,” they are now officially Umbraco Documentation Curators 🤩

The Documentation Curators fully dressed up for UmbracoTees Friday a couple of weeks back.

With 5 “full-time” Documentation Curators and 1 Umbraco HQ steward, it’s going to be another smashing year for the Umbraco documentation, I’m sure of it.

Now, with Sophie and Busra joining the team as curators, does that mean that we will open up for new internships again? Yes, it sure does.

However, we will not be opening for new applicants this spring. Instead, we’ve decided to wait till the fall when the rest of the community teams will also open for applications.

With that said, we’re always happy to accept any help and contributions to the Umbraco Docs! Do you have an idea for a new article, a new tutorial, or perhaps you’ve found places where the docs currently lack information? Let us know, and we’ll be more than happy to help if you need any assistance around the whole contribution process 😄

 

Did someone say code samples!?

When it comes to users/readers of the documentation, there are two kinds. There are those who come to the docs because something in their implementation has broken or they’re running into errors when testing out new functionalities. Then, there are those who come to the docs to learn what is possible and to get a good understanding of a feature or product before diving into the implementation.

Now, how to accommodate both can be a big challenge. It means that we need to have a sufficient amount of conceptual and reference docs as well as enough real-life samples and use-cases. That way, we can both explain how products or features work while we show how they can actually be used.

 One of the main things that we have found that’s currently missing from our documentation is samples! We do not have enough code samples showing people how to actually use all the great features that our products have.

Recently, a lot of code samples were added to a specific section of our documentation… Let me tell you a little story:

In Umbraco, there is a large collection of built-in property editors that lets you add different types of data to your content. It could be the Rich Text Editor, the Checkbox, or perhaps the Media Picker. In some cases, you might need to be able to add values to these properties programmatically, instead of through the Content section in the backoffice.
Now, we have articles for each of these property editors, and these articles provide information on how to configure the editors and how to render data based on these editors on your templates and views.

A quick sneak-peek on one of the new code snippets - this shows how you can programmatically add data to a Checkbox property.

As of this December, all these articles now include samples on how to add values to the editors programmatically. This is especially useful when you’re creating or updating content on your website programmatically and you need to figure out how to add specific data to the content.
A BIG shoutout to Erik-Jan Westendorp for adding all these code snippets - he actually had a little morning ritual in December where, each day before starting work, he made 1-2 PRs to the Umbraco Docs adding these super helpful samples 🤩 If that’s not dedication, then I do not know what is! H5YR, Erik 🎉

Feel free to let Erik-Jan Westendorp just how awesome he is on Twitter!

This is a great example of how adding useful code samples to articles - which so far only described the feature and what it did - now also gives you, the readers, some examples of how the editors can actually be used in a real-life Umbraco project. Articles now explain the concept of each of the property editors, show how they look and can be implemented, and give examples of how data can be added to each of them programmatically. How great is that!?

Do you have an idea of some code samples that could be added to our docs? Then that’s a great place to start contributing as we’re always looking for more real-life samples to accompany our existing collection or articles 💪

 

Numbers...

And with that, we’ve almost reached the end...and it’s time for some numbers! We’re almost through the second month of 2021 - how have we been doing on the docs side of things this year? Let’s take a look.

As you can see, January and February have been a couple of busy months for the Umbraco documentation. 49 PRs have been merged already! They include updates related to new and updated Umbraco Cloud functionalities, some updated code samples, a brand new tutorial on creating a Members section on your website and so much more!

But that’s not all! On the new Github repository for the documentation for the next Umbraco major we’ve already received 7 PR and with most of those already merged in, a whopping 15 articles (!!) both new and updated are already available 🎉

When you consider that the product is currently still in alpha, I’d say we’re in for a pretty good head-start on the documentation side of things! A huge thanks to all who have contributed so far - be it part of your regular workload or as a voluntary contribution 🤩 #H5YR

That’s all from me for now. I’ll be back again in a couple of months with another update from the Umbraco docs.

Until then,

// Sofie