[DONE] Immediate action plan for reviewing content

Archive Documentation
1

Final decision: Postponed

This suggestion never got much feedback. I think it still needs some more work, ideally by a group of people to find a better workflow for reviewing content. Can be revisited at a later time.

Motivation

Currently not all manuals are up to date. Some are not only not up to date but have other serious issues as well (e.g. Extbase book). We are aware of this but have not been able to solve this yet (though considerable time and effort has already gone into this and it is a continuous process).

When reviewing, there are many things to consider: Is content correct, up-to-date, is language correct, is it well readable, the structure etc. Also, I think some general things must be decided, for example general structure of documentation etc. However, we only have limited time. So, I think we should focus on the biggest problems, most relevant manuals and where the most improvements can be made with least effort first. Any other improvements are not discouraged but we should try to focus on first things first.

In general, I would like to review more systematically. And if the work is done in collaboration, it is important to be able to determine where the other left off, what was already reviewed and where to focus next. Apart from using issues for immediate problems, I have not really found a good solution for this yet. Ideal would be a possibility to just mark a page as reviewed with a simple click, but currently we do not have a solution for this.

Once everything is up to date and only updates are necessary for the items in the Changelog, this will become easier but we are not there yet.

Objective of this decision

Introduce “the plan” for systematic review and priorities, get feedback and ideas for further refining it.

The plan

  1. Assess current state of manuals. Focus mostly on master branch, do not consider older versions. A very broad and general “status” can be determined by superficially glancing through.

    This list can be updated:

    https://docs.typo3.org/m/typo3/team-t3docteam/master/en-us/OverviewOfManuals/00ListOfManualsReview.html

  2. Prioritize manuals

    Excluding the ones that are already ok for “master” branch (Getting Started, Contribution Guide and Writing Documentation) and the ones that will get removed (e.g. Extbase / Fluid guide), prioritize the rest: Highest priority first:

    • TYPO3 Explained
    • Extbase / Fluid Book
    • TCA reference
    • TypoScript ref
    • TSconfig ref
    • Installation Guide
    • Frontend Localization Guide: should be evaluated if this can be moved to TYPO3 Explained and integrated with already existing information on sites module and localization.
    • Sitepackage Tutorial
    • templating tutorial
    • Tutorial for editors

  3. For the manuals that are partly up-to-date and too long to review in one sitting by one person, create an easy to check off checklist for reviewing:

    For T3 Explained focus mostly on getting it updated and missing parts added.

    For Extbase / Fluid book also focus on shortening text, improving the language and generally making it well readable.

  4. Ideally, while reviewing the problems should be fixed and text updated. But since this takes considerably more time, a first step can just check off each chapter that is ok and add issues for the ones that are not.

  5. Create issues for missing content (label: “content missing”).

  6. Work on solving remaining problems