“The #1 issue with Umbraco, whether contributing to or using it, is a lack of documentation”
“There needs to be dedicated documentation support. So much is still outdated or incomplete, and it repels newcomers. Documentation is the code-equivalent of a ‘first impression’. ”
As you might have guessed, this was some of the feedback we got from the survey we conducted on Our in April 2017. An important eye-opener!
And with 64% on Our finding the Umbraco documentation a barrier, we knew we had to do something - so we did:
- September 2017: Sofie, Umbraco HQ Support Warrior, started dedicating time for working on the documentation (Read about her work with the documentation so far in her blog post series “Sofie’s Docs Diary”: Keeping the Umbraco documentation up-to-date, Umbraco Cloud)
- January 2018: Putting together a skilled Documentation team. More help is allocated to the Umbraco documentation, with coordination between the community and HQ (that’s the initiative Ilham and Jeavon will let you in on in the following)
Once upon a time, there was no documentation…
But first, let’s go back to where it all started:
The Umbraco documentation project was born on the 15th June 2012 upstairs in “The Box” room at Codegarden when about 10 developers joined an open space session with Per Ploug and me, Jeavon Leopold, to kick off an initiative to document Umbraco v4.
Since then there have been over 2,500 commits from over 160 contributors! That’s actually quite amazing!
Despite the immense effort over the last 6 years, we still hear that documentation is a major issue for many people using Umbraco so we have set about creating a team of documentation curators to manage the UmbracoDocs repository.
The new Umbraco Documentation Team
The aim of the team is to improve the “pulse” of the repo. The team are available to manage PR’s, generate missing documentation and encourage more contributors to get involved.
The majority of the documentation curators are volunteers from the Umbraco community. Curators who’ll help make it more straightforward for you to contribute to the documentation and ensure documentation PRs get handled in a timely manner, so we keep having fresh and relevant Umbraco documentation on Our. Good for you, us and Umbraco newbies (including that new colleague of yours!)
Meet the Curators:
The team of documentation curators is made up of Sofie, Jeavon, Marc, and Damiaan, (with a small help from me, Ilham) - all of whom have given huge amounts of their time already to the documentation and will continue to do so!
The team members have been carefully picked due to their passion and dedication to the Umbraco project and their understanding and appreciation for good, solid Umbraco documentation. Let’s meet them:
Working with Umbraco since 2007, Umbraco V4.0
“I am the technical director for Crumpled Dog, an Umbraco Gold Partner based in London, UK. I am also a current Umbraco MVP, a core contributor (I have contributed something to every major and minor release since v7.1), the creator and maintainer of several successful Umbraco packages and, most importantly, a member of the amazing community of people who also love to use Umbraco.”
My particular area of Umbraco expertise is Property Value Converters, Imaging, Azure and, more recently, Health Checks.
I began the documentation project with Per as in the absence of any formal Umbraco documentation I had created internal Umbraco documentation for my growing team at Crumpled Dog. We found ourselves repeatedly covering the same topics and it made sense to share the work we had been doing and we continue to share to this day.”
Marc (@marcemarc )
Working with Umbraco since 2012
“I work for the popular Umbraco Gold Partner, Moriyama in the UK.”
Day to day, I’m working with Umbraco, helping improve and build Umbraco site implementations, running training courses, and explaining how 'bits and pieces' work to developers and editors across the many different implementations and organisations that Moriyama support.
When I started working with Umbraco, I often said the 'documentation is rubbish' without really any malice or realisation what that might mean to people actively maintaining it, it's a lazy observation and I never realised that I could play a part in making the docs better, but what I've found out over the years is… that when I've worked something out, and I've thought, "oh, they should have that in the docs", I've realised... that 'I am they', (and so are you) and you/I - well, we can add useful information to the docs to help each other out”
Working with Umbraco since 2016, version 7.5.6.
“You might know me from “Sofie in the Cloud” or “Sofie’s docs diary” - or perhaps we’ve chatted together about Umbraco Cloud? I’m Sofie (as if you haven’t realised that by now 😉 ) and I work at the Umbraco HQ.
My official title is “Support Warrior” as part of HQ’s fantastic support team - but as you can see, my role has shifted a bit as I’m spending more and more time on updating the Umbraco documentation. I suppose that’s kind of support as well, right?
Being part of the support team, I’ve come to realise how important good documentation is. Both to our clients but also to ourselves. It’s such a big helping hand and you know what - working on documentation is very rewarding because of that. I’ve had so many nice comments and high-fives from colleagues and community members since i started writing documentation. So I can only recommend that you get started as well 😉 ”
Working with Umbraco since Umbraco version 4.0.
"I am a developer at the Umbraco Certified Partner agency Umbrace and one of the few fully Certified Umbraco Masters in Belgium (as if Belgium is a reference 😊).
Over the years I learned – sometimes the hard way – what you shouldn’t do when using Umbraco. Over the years, I also learned that helping other people is lots of fun. And meeting these people is even more fun.
Why I care about documentation? Sharing is caring. And I do care a lot. I do care about the people around me. Not only my friendly and intelligent colleagues, but also every developer trying to use the system I love. Few people know it, but the documentation section is a goldmine of good information helping you to build better websites. But sometimes good is not enough. I believe we could leverage documentation to a next level. Together with a community which is always open for improvement. I believe we can care together about others"
And then there’s me, Ilham, who can’t really brag about technical Umbraco skills like the above (told you I was only a little help to this team 😉 ). Instead, I will be helping as a community liaison making sure that the curators have access to the information they need as well as getting useful feedback from HQ.
So that’s the Umbraco Documentation Curators. Quite a solid team, right? But hey, they won’t have anything to curate without your help.
We need help from the whole Umbraco community!
We want to hear your ideas on what documentation is missing and also if you have seen any great examples of online documentation that we should take inspiration from. It doesn't matter if you are not a fantastic technical writer, but if you would like to have a stab at creating something that’s missing, or you have written something but just don't know where it should go - get in contact, we can help!
Remember - It is your documentation too. You can contribute - that doesn't necessarily mean writing documentation; reporting what was helpful, what fell short of what you needed, or you found something but not where you expected it to be - let us know - it all helps.
And if you do feel like writing something - do it! Writing documentation does improve you as a developer (scientific fact!). If you see or hear someone say "The documentation is rubbish"... harvest their example, create an issue on the tracker and let’s get it fixed together.
Who knows - maybe this team is going to kick-start a bunch of new contributors to the Umbraco documentation. We hope so. Afterall, it’s a very valuable resource to many thousands of Umbracians - current as well as future ones.
The next you’ll hear from us will be a blog post about how best to contribute to the documentation so you know exactly which steps to take. But if this post gave you some motivation, please don’t hold back😃