Contributing to the Umbraco Documentation

Story time!

About 3 months ago, Umbraco 8 was released (yay!), and during that time I started to experiment with Unit Testing some basic concepts in Umbraco 8, and I found that there was very little (none) official documentation available on how to get started with Unit Testing in Umbraco. I love Unit Testing almost as much as I love working with Umbraco. But I’ve come to realize that in order for unit tests to be written, it needs to be simple to get started with a minimal amount of mocking required, otherwise it’s very easy to “forget” to write the tests.

There are some great blog posts scattered around the internet on Unit Testing in Umbraco but there’s no “official documentation” that someone completely new to Umbraco or Unit Testing can easily find and start learning from. Until now! :)

But before you jump to the documentation, I want to share my very first “documentation story” with you. It’s a step-by-step story so you know what I did, how I did it, why I did it and, of course, the result. And maybe (hopefully) you’ll even end up getting inspired:

Get the discussion going

The first thing I did just to make sure that I haven’t completely missed something obvious was to start a discussion on Our, Umbraco’s friendly community forum, just to see how others prefer to do Unit Testing and how to start testing Umbraco version 8:

And as always, there were some great examples, help and discussions shared in the forum thread. #h5yr to everyone! Once I felt that this was actually something that was missing in the documentation and requested by more than just myself, I felt I had to take this one step further.

Create a feature request

So the next thing I did was creating an issue (or a feature request) for the Umbraco documentation on GitHub, hoping that someone would swoop in, find this issue and save the world from untested code:

And that was it. Or at least that’s what I thought. Pretty quickly I got a response from Umbraco HQ, but it wasn’t exactly the response I had in mind:

I felt a bit embarrassed, to be honest. It had actually never crossed my mind that I could write this documentation myself, even though I had no problem expecting someone else to do it for me. Also, I think that there was a bit of imposter syndrome involved, because “surely I can’t write documentation on Unit Testing, can I? There must be someone better suited for this job, right?” But with a little encouragement from the friendly HQ and a review of my code from the Core team, I felt empowered enough to start writing this documentation.

Time to get to work!

So now I had no excuse but to start writing this documentation myself. I took what I had already posted in the forum thread, packaged it as documentation and added a few extra tests for some well-known concepts in Umbraco (Surface controllers, Render MVC controllers etc), created a pull request and sent it back to HQ. The very next day I got a friendly response saying:

And that was it, I had successfully contributed to the Umbraco documentation!

The result

The result is a brand new section of the Umbraco documentation focusing on Unit Testing:

It’s not final, it’s a start.

I had to stop somewhere just to get something up and going so that others could join in and extend/improve what I’ve started. A few tests are better than no tests at all and at least now we can get the ball rolling and eventually we’ll have working examples of how to test most parts of Umbraco, which in the long term will result in even better and more stable implementations of Umbraco.

So all I want to say with this little story is: if you know any improvements or missing information in Umbraco Documentation, especially now with Umbraco version 8 just released, don't be afraid of submitting a pull request. Don't expect that someone else will do it, do it yourself. Since you are the one who found the missing piece, you’re probably the most qualified person to fix it.

Go for it! :)

Take care of each other, and be safe! ;)

Cheers! Dennis Adolfi