Documentation rework for 4.0
Xerkus opened this issue · comments
Current documentation is severely outdated and does not meet our quality standards.
This is a tracking issue for all documentation improvements that must be done for the next major release.
@settermjd your input on the improved documentation structure would be greatly appreciated.
/cc @froschdesign
A clarification needed:
@settermjd by documentation structure I mean mostly writing structure?? of the documentation from the point of view of the technical writer. A structure for the detailed yet understandable documentation that could be read like a book, if that makes sense.
The documentation of laminas-mvc needs a different structure as other components like laminas-form or laminas-validator. Because laminas-form or laminas-validator consists of many individual elements which can be used individually and a form or a validator is mostly integrated in an application. But laminas-mvc creates the application itself and elements of those applications like a controller can not be used separated.
Therefore I think we need a structure in which the individual sections build on each other and answers all (typical) questions.
A key element should be code samples but no tutorial should be created, we can do that elsewhere. But in the end, the different examples will result in an executable (skeleton) application.
So the idea is, instead of a pure reference we create practical entering guide with all explanations.
Suggestion:
Introduction
Should contain:
- Event-driven system
- Used components
- Benefits of laminas-mvc
Should not contain:
- Application structure
- Module structure
- Bootstrapping application
Installation
Should contain:
- Standard installation
- Installation with skeleton application
Quick Start
Should contain:
- Complete and quick guide to create a module with controller, route, view script.
- Links for each step to sections with detailed descriptions.
Application
- Application structure
- Bootstrapping (e.g. index.php)
- URL rewriting
Configuration
Should contain:
- Default configuration
- Explanations what can be loaded and why
- Dos and don'ts
Module
- Structure
- Loading (Composer)
- Registration
Configuration
Should contain:
- Explanations what can be loaded and why
- Dos and don'ts
Controller
Should contain:
- Creating and registering controllers
- Types of controllers
And the chapter should contain pages which answers (typical) questions and usages for and in a controller:
- Get route parameters
- Template rendering
- Generating a URL
- Redirection
- Adding services
- …
Routing
Should contain:
- Creation of routes
- Links to laminas-router
Should not contain:
- The entire documentation of laminas-router.
Event System
Should contain:
- Creating and registering listeners
- Defined events
Migration
- from v2.X to v2.7
- from v2.X to v3.0
- …
(This is a first version and the work is still in progress.)