DocFX: A new Documentation platform
Since January 2018 we’ve been looking into options for moving the Umbraco Documentation to a new platform that would provide us with more flexibility for the whole project.
We have been playing around with and testing a couple of tools - GitBook and DocFX. Two very different platforms.
Gitbook is very "no code / low code" oriented which could be beneficial for the user experience when reading and contributing to the documentation.
DocFX is more tech-heavy and developed by developers for developers. We're already using the platform for the Umbraco API and Backoffice UI documentation.
UPDATE: The project of moving the Documentation to a new platform is now owned by the COMA team at Umbraco HQ. The Documentation Curators will still be involved in the process as we have a lot of experience with both the current platform, Our, and the one's we've been investigating so far.
Documentation Personas (Getting Started)
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.