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.)
- 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.