Contributing to the Umbraco Documentation

A piece of documentation was missing. Dennis did something about it 🙌

Written by:

Did you know that you can contribute to the Umbraco documentation? Yes, you! Developer Dennis Adolfi didn’t know, or, maybe he did, but felt a case of imposter syndrome which held him back… until he got a friendly push. And now he’s the creator of the official Umbraco Unit Testing documentation! H5YR Dennis! Get the full story from Dennis here - you might even end up getting inspired...

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:

Adolfiunittesting2 (1)

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:

Adolfiunittesting2 (1)

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:

Adolfiunittesting5 (1)

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




Adolfiunittesting6 Profile

Dennis Adolfi is a developer at Creuna, living in Gothenburg, Sweden. During his six years of working with Umbraco he’s been an active member of the community by writing several articles & tutorials, hosting events, teaching and helping out in the Umbraco forum, for which he was announced Umbraco MVP in 2016/2017.

He is also an Umbraco Certified Master and he loves Test Driven Development. If you would like to get in touch with him or stay updated, connect with him on LinkedIn.

Loved by developers, used by thousands around the world!

One of the biggest benefits of using Umbraco is that we have the friendliest Open Source community on this planet. A community that's incredibly pro-active, extremely talented and helpful.

If you get an idea for something you would like to build in Umbraco, chances are that someone has already built it. And if you have a question, are looking for documentation or need friendly advice, go ahead and ask on the community forums.

Want to be updated on everything Umbraco?

Sign up for the Umbraco newsletter and get the latest news and special offers sent directly to your inbox