Another Codegarden (the biggest Umbraco conference in the world) has come and gone, and boy! What a week 😍 For most people, Codegarden is a 3½ days event, but for a selected few, it’s even longer than that. Every year a handful of people are invited to join the Umbraco Retreat. From Saturday to Tuesday morning they spent all - well, almost all 😏 - their time on hacking away at Umbraco.
Hm. This is a blog post about Documentation, isn’t it? So, why am I talking about Codegarden and Retreat?
Well, there’s a pretty good reason for that actually!
Three Documentation Curators were invited to the Retreat this year 🎉 Jesper, Damiaan and Jeavon - joined by Lotte Pitcher - spent 3 days working on something VERY exciting.
I’ll let Jesper tell you all about it:
What happens at retreat, stays at retreat?
… well, not at all actually, because I’ve been told to spill the beans:
My name is Jesper and I’m a proud member of the Documentation Curators. I’ve joined Sofie today in this blog post, to talk about my first ever retreat. I was very excited to be invited and get to see what all the fuss was about!
I was invited along with the Documentation Curators to work on improvements to the Umbraco documentation.
Since the Documentation Curators visited Umbraco HQ back in November 2018, we have been working on a way to restructure the documentation to make it easier to get started with and contribute to.
We’ve been reviewing the current tools and setup we use, and during the retreat, we worked on a new documentation site that supports a lot of new features, makes it easier for us to deploy changes and is more flexible in the documentation structure. How exciting is that? 🤩
Unfortunately, two of the Documentation Curators; Marc and Sofie, could not join the retreat, but we were lucky enough to have the help of Lotte Pitcher while we were there. Having the viewpoint from a documentation user and contributor was a great help! #H5YR Lotte!
In the end, we managed to have a full working prototype of a new documentation site running. It can do a lot of great things!
What’s the best thing about the new Documentation site?
If you ask me, the strongest feature is that it integrates the C# API documentation into the site itself. You can link to specific endpoints from the API documentation, and you can even write markdown files that improve the descriptions in the API documentation.
Uuuh, when will it be ready?
The site is not quite ready to ship as it is missing one big feature: versioning. We currently have a mix of Umbraco 7 and Umbraco 8 documentation, and we do not want to ship a new documentation site before we can support both versions. A bit of work is still to come. Sofie and I will, of course, keep you updated on any new on this in upcoming “Sofies Docs Diaries”.
Getting a documentation Style Guide up and running
The restructuring of the Documentation was the BIG topic during the retreat weekend, but we also spent some time talking about a Style Guide for the Documentation. As this topic was also on the table during Codegarden 2018, we decided to get things moving. We put together an RFC (Request for Contribution) for a Style Guide. If you have suggestions, you’re more than welcome to join in.
So, as you can hear, the retreat was a very productive couple of days - and don’t worry! We did enjoy a beer or two as well 😉
Thanks to Jesper for sharing his very first retreat experience! 👏 That whole new restructure of the Documentation sounds really exciting, right?
And now, on to one of the “Docs Diary regulars”:
New and updated Documentation 🌟
In my last blog post back in March, it was all about Umbraco 8. That’s about 2-3 months ago and guess what: A bunch of Umbraco 8 documentation has been added since - both new articles and updated ones.
Here’s a quick overview:
Examine and Umbraco 8: Quick start guide
As you might know, Umbraco 8 came with a lot of breaking changes. This included some major changes on how to use Examine. With Shannon's help, Jesper has made a Quickstart guide, on using Examine in Umbraco 8.
That’s not all! He also wrote an article on how to use Examine events in Umbraco 8.
These articles are a great start, but we still need to add even more documentation on Examine in Umbraco 8. To keep track, we’ve created an issue on the Documentation Issue tracker: Missing Examine Docs for v8. Feel free to voice your opinion on what you want documented on this topic.
Unit Testing in Umbraco
Can you believe that we never had any real documentation on how to perform unit tests in Umbraco? 😱
Community member Dennis Adolfi noticed this when he wanted to start doing some, and you know what he did? He wrote an entire article on Unit Testing with Umbraco. #H5YR, Dennis! You can read his inspirational and very honest story about his documentation contribution right here
Azure Blob Storage: Updates for both Umbraco 7 and 8
For a while now, we’ve had a guide on how to setup Azure Blob Storage with an Umbraco Cloud project. A few weeks ago, I updated this article and even made a version on how to set it up with Umbraco 8. I also moved the articles, as they don’t only apply to Umbraco Cloud setups. Thanks to Jeavon for helping me get all the details straight 💪
Umbraco 8 Documentation Status page
You can get a complete overview of all the new and updated Umbraco 8 Documentation on the status page we introduced when launching Umbraco 8. It’s constantly being updated with all the new articles that are being written.
The latest Docs Numbers
Woah, would you look at that!? We’re almost at 300 contributors 😱 That’s really amazing to see.
The numbers are going up, and we still have to work harder in order to keep up with all the contributions - we love it!
That was all from me.
As always, if you feel something is missing in the Documentation or if you want to contribute (like Dennis Adolfi did), go ahead and check out our contribution guidelines. We appreciate all the help we can get 💪
Until next time, Sofie.
