This is the followup of Broken links in docs.plone.org
It is still WIP but should give already some information about the possible future of the docs.
As stated already before and also in the document.
We are trying to see the whole picture not only devs. It is meant for all audiences of the docs.
One more thing, as also stated before, I am pretty sure there are lots of things in the document where you do not agree or even do not understand/see the point why (no offense !)
If so please ask for the reasons and I will happily try to explain !
This document is pretty much a result of lessons learned and lots of talks with other "docs people" of various projects and companies.
Nothing is written in stone, nothing is definitely yet, still it points in the general direction of modern documentation.
Documentation 2.0
Abstract
These document outlines the new "specs" for a better and improved documentation.
We learned a lot of the last years, let us translate all this into better and user orientated documentation.
They key here is user orientated.
We have different audiences and thus different needs.
All of them are equal !
Introduction
From improving the wording, over structure till building and releasing this document (WIP) tries to cover all these steps.
Improvements
Appearance
Make the look and feel better, make it easier for people to identify and find what they are looking for.
This can be done for example with a improved landing-page, with visual improvements and adding boxes per audience.
Example
Use a theme which is focused on presenting content !
Our current one is too distracting.
Examples of content focused themes with less visual interruptions
Redactor Theme
TTD Henry
TTD Docs
Audience
Better and easier distinction between audiences.
If a user is looking for the docs about theming the user is at this moment not interested in docs about ZEODB.
To do so we need to make sure that all docs in the different categories are really:
- straight to the point
- written in the right tone and voice for the category
- understandable
- the user does not get distracted with to much noise (like look and feel, etc)
Style
- "rethink" our terms, for "us" (old plone ppl) lots of our terms makes sense but that is not always the case for newer people.
- shorter items
- consistent style-guide and usage of terms
- consistent and shorter headings
Structure
Improve the structure by moving some parts to other locations.
Our current structure does is not always logical or understandable for (new) developer.
We can improve that by re-locating some parts to other locations and by 'merging' some parts into one chapter.
Examples are here: Installation and developer docs
Further remove/improve the structure to make the docs less nested.
It is often confusing for user that some docs are really deep nested like docs.plone.org/develop/bla/bla/bla/bla
Stay as flat as possible !
README Removal
Currently we are including READMEs from external documentation like bobtemplates.plone.
A README is great for a developer, unfortunately it is less suited for including into documentation.
Besides the wrong tone and goals of a README also the nice buttons of Travis etc are no addition to the docs.
They only add noise and distraction.
These are perfectly fine for a README but less cool in the documentation.
External Removal
Because of historical reasons and the way how the current documentation got structured we still use the directory external.
This is maybe nice and logical for the docs team but this add no extra value for the reader.
Besides that, it also can lead to confusion, because for the (new) reader it is not clear why certain parts of the docs are located under external.
Further is breaks with the structure and consistency of the docs.
Splitting
Splitting the docs into "standalone" parts.
We started already doing that with the training docs.
For example each "main" chapter (installing. theming, developing) should be this way.
By doing so we will be able to make (faster) "canary releases", we can provide a better user experience, etc, etc.
One other huge reason is that by doing so we can run tests against the docs, easier and faster, too.
This also provides ah moments because contributors see their PR faster merged and the tests also reporting only on their changes.
Of course we can choose during a release to do a full or only a chapter release.
Search
- custom search per audience like searching only in theming or installing
- better docs.plone.org/search atm the mix between Agolia and Sphinx is confusing, create a /search with Agolia API.
- If you "click" on the box with your audience you get immediately to the parts of the docs you are looking for,
for example "theming" and then you only see the theming docs, if you click "here" on search you get a custom search (with a button) to search all docs, too.
Branches
Change the way how the docs repository uses branches.
Currently we create a new branch when the Framework Team creates a new main branch of CMFPlone.
The last years and releases have proven that this is not the way.
Because of the pace of development, time, effort, etc, etc. this only creates lots of extra work, because we have to maintain and merge content to even more branches of the docs.
This is time consuming and "error prone" as it also adds confusion, about to with branch to commit to etc.
Because of this we will change the branch model to the following.
master will be cutting edge aka rolling release.
We will build "weekly" unstable docs from this branch.
This branch will be also the branch we most of the commits will happen.
If there is a new release of Plone, we will cut a new branch of the master.
The master keeps to be cutting edge and the new branch will the "last old version".
Testing
CI
We will use a dedicated CI setup for the docs. All tests are running in containers, meaning we can use them better, faster and everywhere.
Tests On Commits
The way how we run tests will change. With the new setup we will test with each commit or PR only the files which are changed.
This has the following advantages:
- tests are faster
- we can better and "easier" improve the docs and its tests
- it is less de-motivating for people, since CI is "only" complaining about "their" commits.
- tests are based on Redactor
Tests On All Docs
Redactor
This is our new test-framework where we can configure the amount of tests and also the level, etc.
Some of the tests we "only" run on release time, like HTML, other ones like style-guide we run always.
Test Overview
- spell-check
- link-check
- line-length
- file-length
- write-good
- style-guide
- white-spaces
- HTML
- ...
- ....
Building
Coster
Coster is the re-written and improved version of papyrus. Here we configure which "external" (like ansible-playbooks and branch) docs we fetch and where we put these in our docs.
Coster can handle rst and md !
Coster also fetches all images we need which are created by our jenkins-robots.
After Coster is done fetching and building the docs, we do run again tests on the created HTML, like HTML validation, accessibility checks, etc, etc.
If these tests pass, Coster will create automatically "ready to run" container images (docker).
Deploying
Each version in own container, plus weekly builds of "unreleased".
Each version like 3, 4, 5 gets a own container.
Coster
Coster creates, tags and uploads the container to Docker Hub.
For "unstable" this will be done, once a week or so.
This is also perfect for local usage, "just" do
docker pull plone/documentation/5
and you get the latest docs of Plone 5.x which you can run locally and also off-line.
Or do
henry serve
Hosting
We will use the new k8 cluster for hosting.
k8 recognizes if there is an new image available and automatically downloads and switched (blue-green) to the new image.
Helper Tools
tbc
Henry
(add henry docs overview)
Coster
(add coster docs overview)
Redactor
(note you can run tests also without Redactor)
that would be super!