Umbraco Tv Gang

Sofies Docs Diary vol. 22 - Docs + Autumn = šŸ§”

Sofie Blogpost
Written by Sofie Toft Kristensen

Autumn is here, and autumn is always a great time to be working with the Umbraco documentation. We always see an increase in contributions during autumn - well, especially during October, and thereā€™s, of course, a very good reason for that! šŸ˜‰ Autumn, also this year, is even more exciting, as it holds an Umbraco festival and a documentation conference šŸ¤©

From Preptember to Hacktober

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 šŸŽ‰

Hacktoberfest

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 šŸ™

More (virtual) conferences, plz!

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 šŸŽ¬

Write the Docs

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:

ā€œTechnobabbleā€

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.

Uno

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.

Uno Marked

ā€¦ That gives some food for thought, doesnā€™t it? šŸ¤”

Creating easy entry points

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 šŸ˜ƒšŸ¤”

Feedback and rating systems?

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 šŸ’Ŗ

Ā 

Getting Started

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!

Umbraco Docs Trello

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 šŸ˜ƒ

Ā 

Quick update on videos

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:Ā 

Ā 

Numbers šŸ”¢

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:

Prstat Oct2020

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.

Docs Numbers Oct2020

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

Loved by developers, used by thousands around the world!

One of the biggest benefits of using Umbraco is that we have the friendliest Open Source community on this planet. A community that's incredibly pro-active, extremely talented and helpful.

If you get an idea for something you would like to build in Umbraco, chances are that someone has already built it. And if you have a question, are looking for documentation or need friendly advice, go ahead and ask on the community forums.

Want to be updated on everything Umbraco?

Sign up for the Umbraco newsletter and get the latest news and special offers sent directly to your inbox