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
