Contributing in 2019
It’s that time of the year again! The holidays are upon us and we’re about to round up the past year. And, oh boy, was 2019 an amazing year in terms of Umbraco Documentation! Sooo many things have happened - it’s almost overwhelming!
For today's blog post, we, The Documentation Curators, have taken a fond look back at everything that happened in the world of Umbraco Documentation in 2019, in order to give you our personal documentary highlights of the year. We will also be looking at some exciting new things for 2020. Ready? Let’s go:
Umbraco 8 ⇒ Versioned documentation
Way back in February, Umbraco 8 was launched and with it: ‘version targeting’ for the Umbraco Documentation! This was a big win for all of us. It gave us the ability to create separate version-specific articles for each feature or topic in the documentation. This is currently achieved using YAML (Yet Another Markup Language), and if you want to learn more about it, I’d suggest you head on over to our contribution guidelines where we have an entire section dedicated to this.
Codegarden Retreat
Just before Codegarden every year, it’s Umbraco tradition that community members are invited to join a “coding retreat” with members from the Umbraco HQ teams. This year, all of the Documentation Curators were invited and during the three days they worked on implementing the Umbraco Documentation on an entirely new platform 🤯
The platform is called DocFX, and before we can start using this platform, there are a few things we need to get in place first - things like versioning! Hopefully, moving to this platform will be one of the big highlights I can write about in 2020 🤞
Read more about this journey in our Codegarden summary blogpost.
Umbraco 8 - Documentation
This will always be a work in progress! But, from having nearly 100 articles of Umbraco 8 documentation at launch, and nobody really knowing just quite what had changed and how much needed to be completely re-explained - we’ve gone to an incredible 181 articles of Umbraco 8 specific documentation in the space of nearly a year 🤯
It has been a community led effort alongside the Umbraco HQ development team. Processes have been put in place to ensure time is allocated to provide documentation hand-in-hand with new Umbraco features…
… but there is still plenty more that can be done - fancy taking on a subject? It’s a great way to learn. Have a look at our ‘up for grabs’ list on the Documentation Issue Tracker.
Styleguide: From RFC to implemented rules
For many years, we have talked about establishing a styleguide for contributions to the Umbraco Documentation. These talks often petered out, rough ideas were not realised or discussed with everyone who might have an interest, which lead discussions at Codegarden to roll over to another year.
The new RFC (Request for Comments) process to the rescue! - by publishing our intentions for the styleguide as an RFC and not trying to define ‘all the rules there might possibly be before’ implementing and taking on board community suggestions, we’ve been able to implement the first edition of the Umbraco Documentation styleguide. Yes, that’s right! 🤩
Want to know more and learn what’s in the styleguide as of now? Check out the very first edition of the Umbraco Documentation Styleguide - psst, you’re more than welcome to contribute to it! 🤫
Hacktoberfest madness
Like last year, Umbraco joined in on Hacktoberfest - the month-long celebration of open-source projects. And once again, it was a HUGE success! On the Documentation repository, we received so many valuable contributions and we appreciate each and every one of them.
Specifically, on the Documentation repository, a total of 132 Pull Requests were made 😎
Community visit in November
In November, all Community teams (The Documentation Curators, the PR Collaborators and the Packages Team) got together for a visit to Umbraco HQ here in Odense, Denmark. It was the second time we did a gathering of this nature. This is an amazing opportunity for those who regularly contribute to the teams virtually, to meet in person and once again, it was a very productive couple of days.
This year, each team worked on writing down a mission, a set of goals and their main tasks. It was an exercise that seemed administrative but actually got us all thinking and left us very inspired. We came up with a bunch of great initiatives for 2020 - more on that later in this post!
Want to know what we and the other two teams wrote down? Head on over to the new “Get Involved” section on Our, where everything has been published 👏
Now, that was 2019 - what about next year?
Get involved in 2020
While 2019 was the year we encouraged everyone to contribute, 2020 will be the year where we want YOU to get involved!
What’s the difference, you ask? Well, by contributing you help with already existing and defined tasks. By getting involved on the other hand, you get to help set the agenda and define the tasks!
So, as I mentioned earlier in the blog post, we have some new initiatives lined up for 2020. Let me tell you a bit more about that. First though, some background info:
The Documentation Curators came together about two years ago as an experiment to see how a community led team would work
Since then, Damiaan, Jeavon, Marc and myself have been ‘curating’ the Umbraco Documentation and the repository behind it. Some of our main goals is to help the community to contribute and provide a continued focus on the project to keep the documentation tumbling ever onwards. We really enjoy the work, and by working together as a team, we’ve learnt a lot from each other about Umbraco and the work involved in curating a busy open-source project.
What if I’d like to be a lot more involved in the documentation project? I’m glad you asked, because now, excitingly, we can reveal that there is a way...
Umbraco HQ and the Documentation Curators proudly presents:
A Documentation Curator Internship ✍🎉
Yep, you heard it right! We’re going to try something completely new - an experiment if you will. We are opening up for anyone to join us in our work curatoring the Umbraco Documentation.
I bet you have a bunch of questions about this, am I right? Don’t worry; I have the answers:
When does this internship start?
The first internship is planned to start on March 4th 2020 and runs until August 27th 2020 - which makes it a total of almost 6 months. The next internship will then start on Wednesday, September 2nd and run until the end of February 2021.
How many interns are you looking for?
We’re looking for 2 interns per 6 months.
When and how will I be able to apply for the internship?
We will open up for applications at the beginning of February 2020 - the exact date will be announced when we get closer - but I think you should start considering if this is something for you already now.
As to how: There will be an online form you will need to fill out - this form will be shared on all platforms at the beginning of February.
We expect to keep the application open for 7-10 days. After that, we’ll select 2 interns to join us for 6 months.
I’ve never done documentation before - will I be able to apply?
Anyone can apply for an internship as a Documentation Curator - that’s the whole point of the internship; It’s for everyone.
It doesn’t matter if you’re brand new to Umbraco, have been writing documentation your entire life or you’re already working for Umbraco HQ. As long as you want to try and work with the Umbraco Documentation, you should apply! We can vouch for the fact that you’ll learn something new 😄
Why an internship?
We have been approached by a few people over the last two years, offering to help more with the documentation and take on specific sections or tasks. Sadly it’s been really hard to help and support their efforts on a regular basis, coordinating with our ongoing goals and the time available from all of us. We felt an official internship might be a tentative way to encourage and support these bursts of community effort properly. And that, without permanently locking anyone into any lifelong commitments to document.
We joked recently when Jesper left to start the Package team that he’d just finished his internship with the Documentation Curators… so maybe, well maybe we should try this officially.
What kind of work will I be doing as an intern?
That entirely depends on you! We will have a list of tasks and projects that you could throw yourself into, but if you have a project or idea for the documentation that you would like to work on during your internship, with our support, we are open to your suggestions!
Oh, and you’ll of course also get to join our bi-weekly Curator meetings, where we talk about documentation related issues, pending PRs and much more.
How much work do you expect me to do?
It’s an internship, not a full time job. We expect to “see you” at our fortnightly meetings (every two weeks), but otherwise, the commitment is very flexible in terms of how many hours you’re able to put into contributing. The main thing, of course, is that you have fun! 😄
And that you feel you’re getting something out of being a part of a community team - whether that be personally or professionally.
Internship - does that mean I will get paid?
No. This is an unpaid internship, and it’s entirely on a volunteer basis.
Umm - What’s in it for me?
Nothing? Oh, plenty! Let me list some of the benefits for you:
- You’ll contribute in a focussed way to an open source project and be lauded for your efforts
- You’ll get support and mentoring from the Documentation Curators
- You will get to go to a team gathering in Odense
- It will look great on your CV
- And last but not least, karma will look after you, somehow...
That’s all the answers I can give you for now. We will of course be publishing much more information about these upcoming internships, and if you have any questions at all you’re more than welcome to get in touch at docs@umbraco.com or reach out to us on Twitter.
The internship is not all that’s happening in 2020. We’re also going to be doing more for Codegarden, we’re gonna initiate some bigger projects on the documentation and we’re of course hoping that even more of you will help us in all of these endeavors!
Now, you can see how 2019 has been great, and how 2020 is going to be just as great - or perhaps even greater 😎
How about some numbers to close off the year?
Numbers …
These numbers are truly inspirational. A total of 132 people have contributed to the Umbraco Documentation in 2019, and a whopping 90 (!!!) of these were first-time contributors! That is just amazing.
A huge THANK YOU and #H5YR to everyone who’s help us keeping the Documentation up to date this year ♥
And that’s all for me for 2019. The only thing left for me to say for 2020;
Are you going to get involved?
Happy Holidays!
// Sofie, out.
