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 š
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.
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? š¤
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!
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:
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