Sofie's Docs Diary Vol. 3: How best to contribute
If you’ve been keeping tabs on the #umbraco hashtag on Twitter lately - or even just the Blog here - you’ll have noticed something amazing happening:
The Umbraco Documentation is finally getting some long-needed attention - and not only from me, but from some very dedicated people from the community - H5YR to the Documentation Curators! Exciting, right? 😃
For my blog post today, I’m going to give you some tips and tricks on how you can help improve the Umbraco Docs.
But first; what have I been doing since my last update post?
News about the Umbraco Docs
Unlike last time, I haven’t been doing any major changes to the documentation. I’ve mainly been doing lots of small updates to existing articles - and then I’ve given the Power Tools article a new structure!
I’ve also been doing something I’ve really been looking forward to: A much needed clean-up!
I’ve been going through the issue tracker on the Documentation Git repository on Github, cleaning up old entries, closing solves ones etc. The Issue Tracker haven't been getting much attention in a long time, and it was getting a bit outdated - now, getting everything down to just 2 pages from 4, it’s much easier for you and me to get an overview of the issues and the entries are all relevant again.
Not familiar with the Issue Tracker? Well, don’t worry - I’ll get to that in just a little bit… 😉
In much related news, we've had an intern start at HQ in February, and after just two weeks here, Jesper created a PR and got a brand new article published on Our about how to install Umbraco. A very important place to have good documentation when you think about it. H5YR Jesper! 😃
Now it’s time for me to tell you how you contribute; how the Umbraco Documentation works and how easy it is to help improve it:
Documentation and GitHub
I know I’ve probably mentioned this before; the Umbraco documentation is just as open-source as the Umbraco CMS. This means that you can easily contribute and help us keep the documentation up-to-date.
You can find all the Documentation in a public git repository on GitHub.
Pro-tip: An easy way to access this repo is by using the link we’ve placed on every article - that’ll send you directly to that article on GitHub. Neat, right?
You see something in the documentation on Our that needs updating? Simply click the "Edit" button and make it happen
There are two ways you can contribute to the documentation. Let’s dive deeper into both of these:
I mentioned the Issue Tracker earlier - this is one way to contribute to the documentation!
Okay, maybe it's not as much contributing as it is telling us about something that you feel might be missing from the documentation or perhaps you found a broken link somewhere. It's a place where we can keep track of things we need to fix, add or update within the documentation!
The Issue Tracker is also a good place to go if you are not 100% sure how to update the documentation or if you have something that you’d like to add to the documentation, but you are not sure exactly where to put it.
Example of things to add on the issue tracker:
- Broken links
- When you come across something that hasn’t been documented
- Outdated documentation
And even though I’m saying it’s not “contribution” as such - it’s still extremely important. Just think about how valuable it will be for the next Umbracian reading the article that the links are now working because you made us aware of it!
Pull Requests (PRs)
Another - and more direct - way of contributing to the documentation is by making Pull Requests.
What does this entail you might ask?
With the Issue Tracker you are making us aware of the fact that something is missing or out-dated - with Pull Requests (PR’s) you get to request a specific change or update to the documentation. Basically, suggest the actual fix.
How? - You make the change yourself and then you request us to review it (that's what we call a Pull Request) and pull it into the Master documentation - and if it’s all good, we’ll of course make the change happen!
Let’s say you’ve found a typo or a syntax error in one of the articles on the documentation, and you know how to correct it.
Follow these simple steps to make a PR:
- Click the Edit button at the top of the article - You are now seeing the same article - but in the Github repository!
- Find and click the little pencil icon ✐
- Now it’s time to find and correct the typos or syntax errors!
- The Umbraco Documentation is written using MarkDown syntax
- Once you are done, you can preview the changes
- When you are happy with the changes, add a title and a description to the change you’ve made and click Propose file change
- You can now review the changes and finally Create pull request
- And Voila! You’ve made a PR 🎉
Here’s a little demo showing the process:
For the heavier stuff
For bigger contributions like, if you find an entire section is missing or if you want to make some major changes to a section, it’s recommended that you put this on the Issue Tracker first. Then you can ask one of us - The Documentation Curators - to assign it to you, which will let others know that you are working on this - just in case someone else will have same idea. But also to make sure you are not spending hours and hours on something that’s already being worked on by someone else.
If the coast is clear, assign the task to yourself in the Issue Tracker and start working on that PR! 😉
I’ve gathered some current numbers from the Documentation Github repo:
Already 25 PR's in 2018 - wooop! Keep 'em coming!
Time to get your Git on
Feel inspired? Good news is that you don’t have to go search for an issue or improvement in order to help out - go to the Issue Tracker and see what needs improvement and get started right away!
Me and my fellow documentation curators are always keeping a close eye on the Issue Tracker and the Pull Requests - and we really appreciate all the help we can get, and all the work you are already doing! 😃
- Sofie 😊