In the Documentation Curators team, we always have a lot of stuff going on. Here you can learn more about each of the projects we're working on.
DocFX: A new Documentation platform
Since January 2018 we’ve been looking into options for moving the Umbraco Documentation to a new platform which would provide us with more flexibility for the whole project.
We’ve chosen to go with a tool developed by Microsoft called DocFX. It’s a tool already used for the Umbraco API and Backoffice UI documentation, and we thought it was a great fit for the official Umbraco Documentation as well.
At Codegarden 2019, Jeavon, Damiaan, and Jesper presented a short demo of how this would work. However, since versioning has become quite important to the documentation (V7/V8/Vnext), we need to wait for the next version of DocFX before we can really move forward with earnest with this. It is tantalizingly close to just what we need.
In May 2020 we had another go at it, trying to spin up the Umbraco Documentation using DocFX. Even though it wasn’t the great success we’d all been hoping for, it has still left us optimistic in terms of the tool we’ve chosen and in terms of this being a great step forward and an improvement to the documentation in general.
We look forward to sharing more about this project with you all when we have something more exciting to show off.
Another big project that we’re continuously working on is defining personas for the documentation in order to create better “entry points”, better ways for “Getting Started” with the documentation and with Umbraco in general.
The ‘first impression’ of using the documentation and getting started, is often the first impression people will form about Umbraco and the Community. That’s also why it’s so important to get this experience right.
One of the common criticisms of the existing documentation is it tries to cover all options for all people, often in the same sentence! The main challenge is that ‘Getting started’ means different things to different people - eg ‘how to install’ or ‘how to login’ or ‘how to design doc types’ or ‘how to edit content’ etc.
The goal of creating the personas is therefore to help signpost people quickly to the right ‘getting started’ place for their getting started context.
So it might sound pretty straightforward, but it has turned out to be quite a large task. We started it about a year and a half ago, but it has been stop-start and the work has just been picked up by our two “interns”, Sophie and Busra. They’ve done a great job so far, and we’ve managed to map out a set of different personas: Project Managers, Editors, Implementers, Developers, and Engineers. Our next task here is to define where each of these personas would need to start when meeting Umbraco for the first time.
It’s a challenging task, but we’re all learning a lot about Umbraco and the Umbraco users throughout the process.
Umbraco 7 --> Umbraco 8
Since Umbraco 8 was released back in February 2019, there are still some parts of the Umbraco Documentation that needs to be updated for the version. That means that there are articles for Umbraco 7 which still needs to be verified against Umbraco 8 and in many cases also updated.
This is also one of the tasks that we’re constantly working on. Mostly, we’re focussing our efforts here around getting you guys to help out.
Look for the needs-v8-docs label on the Documentation Issue Tracker, or check the versioning label on a specific article, to get an indication of whether the article is updated for Umbraco 8 or not.
We’ve also got our hands on some smaller projects that we work on from time to time.
We have plans to create a new template for the Services articles in order to streamline these articles and add some “real life” samples to them as well.
We’ve also got a plan to start creating a Cheat Sheet for Umbraco 8.
We’re working on how best to handle the new articles on the .NET Core version of Umbraco.