Has it already been two months since the last update from me and the documentation teams? 😱 It sure looks like it. But here I am - back with another update for you all. And this time it’s packed with a lot of exciting stuff; Hacktoberfest, 2 virtual conferences - one about Umbraco and one about documentation 🤩
As I might have already mentioned, a lot of things have happened over the last couple of months. The primary focus on September - or should we call it “Preptember”? - was on getting ready for October, where we are once again joining Hacktoberfest - the month-long celebration of open-source 🎉
Make sure you check out all the juicy details about the event, and if you haven’t already; October isn’t over yet: You still have a couple more days to join the celebrations 👕🌳
And don’t worry if you don’t make it in time! The Umbraco Documentation is open-source all year round, so really, you can contribute whenever you want, and just as much as you want to. Isn’t’ that great? 😃
The status so far is, that a total of 80 Pull Requests have been made on the Umbraco documentation during October - we’ve merged 66 of them, and will hopefully get to merge the rest before long 👏 Thanks to all who have contributed so far! We really appreciate the help 🙏
Yes. We all know very well that this year has been a lot different in terms of all the festivals and conferences we’ve been able to attend. Still, this October, the first-ever virtual Umbraco conference was held: The DUUG Fest 2020 🎉
It was a super great event, with a lot of talks about Umbraco related stuff and a lot of relevant topics were brought up in the so-called “Round table” sessions.
Now, why is this relevant to mention in a blog post about documentation? Well, it’s actually super relevant, as one of our Curator “Interns”, Busra Parnell, did a talk on this conference 👏 She talked about her experiences with getting started with Umbraco, about getting into the Umbraco Community and about getting started on the Documentation Curators team - and finally, she talked about the work her and Sophie have been doing with the “Getting Started” section in the Umbraco docs… Sensing a theme here? 🤔
Her talk was called “Getting started with Getting Started”. A very fitting title for all the things she has been “getting started on” the past few years.
It’s a very good talk, and it has some great points about the plans we have with the “Getting Started” section. If you missed it at the festival - or if you just want to re-watch it, you can find it on the Umbraco Community Youtube channel, where you can also find all the other great talks and sessions from the festival 🎬
Last year in September, I got to go to beautiful Prague to attend the annual Write the Docs conference held there. This year, my Umbraco HQ docs team and I, went to some meeting facilities 10 minutes away from Umbraco HQ to attend the 100% virtual Write the Docs Prague 2020 conference. Some of the Curators (the community docs team) joined as well, albeit remotely.
Not sure what Write the Docs is? To put it briefly: It’s a community of “documentarians” and people who care about or are somehow involved in documentation. You can learn much more about the community here: Write the Docs.
Attending the conference virtually was a very different experience, but it was still a very good experience. It was just as inspiring, relevant, and interesting as last year. Meeting like-minded people who work with documentation on a daily basis - just like I do - is such a joy and I’m always amazed at how much I learn from these interactions and sessions.
OK. Here are a few highlights from the event:
The term “technobabble” came up in one of the sessions, and I thought it was kind of catchy. It really captures the essence of texts and articles that have way too much jargon, way too many acronyms, and just, in general, a lot of technical information that people without a background in tech wouldn’t have a chance to understand.
Does the Umbraco Documentation have an issue with technobabble? Oh, yes we do. I would even go so far as to say we have a fairly big issue with this. Especially in the sections where we have documentation for our more content editor focussed products, like Umbraco Uno.
Take a look at this example here:
This text here below is from the landing page in the Umbraco Uno documentation.
The interesting thing happens in this next image - it’s the same text as above but I’ve tried to mark all the technobabble and unexplained acronyms.
… That gives some food for thought, doesn’t it? 🤔
Even though we have tried to write some guides and set up some systems, it is still a bit complicated to contribute to the Umbraco documentation. Creating easier entry points and lowering the barrier for contributions was one of the more general themes throughout the Write the Docs conference this year.
This is obviously a super relevant topic for us, as the Umbraco documentation is open-source. We know that we need to lower the barrier for contributing and to make it easy for new-comers to get started. Should it be more thorough guides and tutorials? Should we create a flatter structure for the topics and articles? Or perhaps we need to switch to a completely different platform to create these easier entry points?
I do not have the answers for you today, unfortunately. It’s something we’ll be looking into, and hopefully, one day, contributing to the Umbraco Documentation will be as easy as reading it 😃🤔
Now, I’m not a huge fan of mathematics, but luckily it looks like gathering statistics and feedback on our documentation can be automated 😅 Some of it already is, however, we could do a lot more in this area.
Imagine if you could rate an article once you’ve read it. If the article helped you, you could give it a big happy emoji, or if it left you even more confused than before, you could let us know by adding some comments along with a sad or frustrated emoji. With feedback like this, we would know a lot more about which areas and sections of the documentation we need to improve.
None of what I’ve mentioned here are new things. It’s all things we’ve thought about and talked about before both in the community team and here at Umbraco HQ. Seeing the topics discussed and presented at the conference last week put some extra fuel to these ideas and sparked some new energy into it.
There are some low-hanging fruits and there are some bigger projects, and not everything will be done overnight. As always, you can count on us to continue to improve the documentation and the documentation platform 💪
Now for something a little different; An update on one of the things we in the Documentation Curators team are working on:
Hi 👋 Sophie here, with a little update on the “Getting Started”. Since we last ‘spoke’, the team, Busra and I have been focusing on the content and structure of this section and created an extensive Trello board to guide our minds!
As you might know from reading our previous blog post we’ve been breaking down some personas and have been working to establish what each persona would find useful from the documentation. We’ve broken them down into 7 key topics: Managing an Umbraco project, Editing, Creating sites, Developing, Extending, Hosting and Where can I get further help?
We added a list of questions underneath each persona to help us understand what they would be using the Umbraco Docs for. For example under ‘Creating websites with Umbraco’ we have questions such as “Which templates, CSS and Javascript will work best with an Umbraco site?”
At the moment we are in the process of converting the Trello board data into a more structured document and we are cross-referencing with Docs to pinpoint what we have and more importantly what we don’t.
And so, the work continues! We’ll shoot more updates at you, as we get closer to the finish line 😃
Before we jump into the numbers game, I wanted to take the opportunity and share with you all some updates on the work me and my Umbraco HQ team have been doing with videos.
On our Youtube channel, UmbracoHQ, we have a bunch of videos about how to work with and troubleshoot with Umbraco Cloud. We’ve also started to grow the collection of Umbraco Heartcore tutorials and most recently we’ve started to add Umbraco Uno tutorials as well. The latest additions have been added just this week, so go check it out!
A couple of weeks back, we also added some new fresh content to UmbracoTV. We’ve been focussing on getting out some material for content editors - a group of people who might not have the most technical knowledge. The challenge has of course been to avoid too much “technobabble” 😉
You can find the latest UmbracoTV chapter for content editors right here:
I realize it’s been a while since I’ve shown you some numbers for the documentation, so I thought I’d do that today.
First, a graph:
This is the activity on the Umbraco documentation since March 2020, which was when I last gave you some numbers. As per usual, it was fairly quiet over the summer, and all in all a some-what steady 8 months 👏
Now, as I used to, I’ve put together some numbers of my own, in order to compare with the state of things from last time - which in this case, will be March.
Let’s take a look.
Wow! 🤯 Check out the increase in contributors! We’re up 34 contributors since March - that’s fantastic. I love to see how more and more people are starting to help out with the Umbraco documentation ♥
Also, the amount of merged PRs looks really good! 👏
Once again a huge THANK YOU and H5YR to all who help out with the Umbraco documentation!
That’s all from this update.
Stay safe ♥
/Sofie and the rest of the Umbraco documentarians
I have decided to nickname the summer of 2020 “The Summer of Documentation” as I have been really overwhelmed with all the recent activity on the Umbraco Documentation. Let me tell you all about it in this update on all-things documentation and TV… wait, what? TV? Yes, keep reading, and it’ll all make sense 😄