First things first: About two years ago we were planning our first docs sprint and I think we made great progress since. Neos development did not stop either so as of today we already have some outdatet content. In addition to missing content.
I suggest the following as a remedy:
Each page (maybe even every node (section) should show when it was last edited, last reviewed and by whom.
A public page should list the oldest not reviewed pages so the community can quickly check topics themselfes (even without backend access).
I suggest every piece of content should be at least reviewed every 12 months. As of our release schedule we should think about reducing it to 6 months if this goes well.
Every page should have a content owner that is primarily responsible for updating and reviewing the content. We can use this to manually create GitHub issues for reviewing. At least this will provide a first contact person who volunteers to answer questions or redirect them. Alternative: Create a general list of subjects and subject matter experts (maybe even more than one per topic).
If the page is due for review a banner is automatically shown on the page. (“This page was last reviewed on 1. May 2019. It was automatically marked for review but some content may be out of date.”)
Host online sprints (“docathons”) for updating, reviewing and creating docs. Maybe host a yearly docs sprint like we did in fall 2018. I think that good docs are actually the main selling point for complex products like Neos. Maybe we’ll find a professional Technical Writer who to aid us in creating good docs. (With funding of course.)
Docathon Goals:
Review and update existing content.
Create clear writing promts for missing content. That includes new manual pages, tutorials, updating content for Neos 5/6, changing examples with Fluid to AFX.
Since there is a small group participating in actually writing the docs I envision that we’ll clearly map out todos (to the point where actually only code and a draft explanation needs to be written) so others from the Neos team can help.
I assume that the entry bar is just to high for our devs. They need to find what content needs to be written, envision a strucuture, think about the target audiences and what do they need to know, then start to actually write the content, copyediting and stuff.
I’d like to shorten this process to the point where our devs just write example code and some rough explanations. Then others can take over and finish those articles.
Personal note: I don’t use Neos in my professional work (or even code at all) but do it as a hobby. I hope nobody is offended when I come around to suggest new things while others are writing far more content than I ever did.
There is one thing in addition to your notes that keeps coming up in my mind:
Not all, but some other docs differentiate their documentation by versions of their software so that people can look up how the software used to work in version X. So, if we’re keeping the Neos docs always up-to-date, this would not be possible. Maybe this isn’t an issue. Just wanted it to be considered
That is true. When switching from RTD to Neos I made the case against versioned docs because high level explanations apply to more than one version.
Comparing differences between supported version side by side increases the understanding of the system. So that’s what we are trying to do. Code / API / Configuration refrences are therefore still version by RTD.
Later we might might support different versions through Content Dimesions.
Thx for your initiative!
I also liked your approach to have a interview, record it and distill it to enhance the existing documentation.
I agree to what you propose. I think we can find topic experts but I wouldn’t put people in charge of pages. I fear it wouldn’t work well as we are already a bit stretched thin currently.
As we discussed we should also update the docs.neos.io soon and improve the performance further if necessary. The installation is a bit outdated.
While you are right, often a reason that things are not done is because they are not visible. Technical solutions can help make things more visible. That’s the reason why I especially like the points 1+2 - they are relatively easily done, but could maybe improve things a bit already.
Wish we could do something like that for RTD.
They need to find what content needs to be written, envision a strucuture, think about the target audiences and what do they need to know, then start to actually write the content
Indeed! Writing docs has quite a few (mental) barriers, especially when you’re not starting out new. Things need to be considered in relation to each other, the bigger picture needs to be taken account of, you should not write something contradicting something at another place, adhering to existing writing styles, not writing too much, not too little, keep the target audience in mind, etc… Writing IS HARD. I’d even go so far as saying it’s at least as hard as writing code. I’m confident writing code, but I’m struggling with writing docs. But good docs are equally important to good code. Having awesome docs for a shitty product is bad, but having shitty docs for an awesome product is also bad.
I’m currently struggling A HELL OF A LOT with .NET and the most frustrating part is the really bad documentation. The base documentation is purely a technical copy of the interfaces without any enlightening notes whatsoever. If the naming of things was explicit all the time, that could work in some cases, but ofc it isn’t, so you’re left with guesswork. The bulk resource of useful information comes from StackOverflow et. al. but their complete neglection of API design lead to at least 3 different solutions for every single problem, depending on what version of the framework (and runtime!) and the miriad of packages are used. Then, every couple new versions of a package, they completely renamed the package, so you have WindowsAzure.Storage, Microsoft.Azure.Storage.* and latest Azure.Storage.* all responsible for the same thing. Of course no one ever mentions the name of the package you have to install for a given code snippet to work. They move and break things so fast, that their own depending packages can’t keep up, let alone the documentation. So you have packages that are just not available in a version compatible with a given runtime/framework, even though it’s part of the official SDK, but are suggested to use that latest version at various places.
In my mind this could include everyone on the Neos Core Team.
Quick example: Martin would be a great owner of the AFX and Fusion topics as he has a great knowledge in these areas and is probably aware of all changes that are happening in this space. If he does not want to write the docs then he could find someone to do it for him. But this would place the burden of updating the docs on him. Even dropping some lines here in the forum or in the slack channel might get things going. (e.g. “In version 6 we dropped support for x and y is now discouraged. Also we have this cool new feature. Can someone extend the docs for me?”)
Other projects have policies that require docs to be present for every PR. Otherwise they will not get merged. (At least in theory…)
I completely agree with you. There is nothing stopping us from having perfect docs right now. The first two suggestions are not only for the writers but for our users.
They need to know if the current piece of content is up to date. We have a lot of code examples. Someone might try them in Neos 5 and it could be broken. Experiences like this weaken the trust in our docs. Or they will wonder why we have only code examples for Neos 3 and 4. What’s about Neos 5?
I did not only suggest something new. I decieded to create new content. Sebastian and I had a quick call talking about configuration. I will use the recorded interview as a basis to update the configuration page in the docs. Depending on my availability I could do this with different topics.
I’d even take a raw and rough draft from a dev and transform it into something usable. Even half baked docs are of great use to me. How can we foster something like this?
all the docs movements!