New outline for the component documentation

[froschdesign]

Caution

Work in progress!

Help wanted

Please add comments and suggestions to improve this idea - to improve the documentation.

---

For consistency and simplification of the component documentation I would suggest a new outline / structure for a component. (This proposed structure is not related to the structure of a single page!)

Goal

• Simplification for the readers of the documentation
• Consistency across the different components

Suggestion

Some principles that should be met:

• flat hierarchy:
  • non-clickable headlines
  • a depth of 1 for the pages
• elements (pages) that MUST to be present:
  • Installation
  • Introduction
  • Quick Start
  • Application Integration
  • Migration (if there are different versions with BC breaks)
  • Cookbook
• elements that SHOULD to be present:
  • Unit Testing (in Cookbook)

New structure of the outline:

Essentials

• Installation
• Introduction
• Quick Start
• (Basics)
• (How it works / Theory of Operation)
• (etc.)

Encrypt and Decrypt, Middleware, etc.

• (List of different types, etc.)

Elements, Helpers, Validators, etc.

• (List of elements, helpers, validators, etc.)

Application Integration

• Usage in a zend-mvc-based Application
• Usage in a zend-expressive Application
• Stand-Alone
• (Usage in other Applications, Frameworks, etc.)

Cookbook

• (How do you register custom View Helpers when using zend-view?)
• (Usage with PSR-11 Containers)
• (When To Use Factories vs Abstract Factories)
• (Best Practices when Creating Modules)
• (etc.)

Migration

• Migration to / from Version 2.x
• Migration to / from Version 1.x

Key Benefits

• full overview of the component
• simple navigation for users
• clear and easy to extend for contributors
• consistent names / headings
• consistent structure between components
• allows collapsing the sections of the navigation
• (…)

Implementation

The implementation can not be done in one single step. It must be done separately for each component.

Example (1)

The following list is a concrete example based on laminas-stratigility:

Essentials

• Installation
• Introduction
• Middleware Basics
• Quick Start

Middleware

• Creating Middleware
• Executing and Composing Middleware
• Error Handlers
• API Reference

Migration

• Migration to Version 3.x
• Migration to Version 2.x

Example (2)

The following list is an example for laminas-hydrator:

Essentials

• Installation
• Introduction
• Quick Start

Hydrators

• ArraySerializable
• ObjectProperty
• Reflection
• ClassMethods
• Delegating
• Aggregate

Strategies for Hydration and Extraction

• Default
• Boolean
• Closure
• Collection
• DateTimeFormatter
• Explode
• Serializable
• Strategy Chain
• Writing Custom Strategies

Naming Strategies

• Identity
• Map
• Underscore
• Composite

Filters

• Introduction
• Get
• Has
• Is
• MethodMatch
• NumberOfParameter
• OptionalParameters
• Composite

Iterators

• Hydrating Iterator
• Hydrating Array Iterator

Application Integration

• Usage in a zend-mvc-based Application
• Usage in a zend-expressive Application

Cookbook

• Use a Hydrator in zend-form
• Use a Hydrator in zend-db
• How to Define a Hydrator for Complex Objects
• Unit Testing

Example (3)

laminas-i18n already implements the new structure: https://docs.laminas.dev/laminas-i18n/

[settermjd]

Can I be a bit annoying and say that testing, at least a basic introduction, should be a requirement. I've read through more than enough components where testing was an after-thought, which turned out to be clear why it was. Because when I attempted to test the component in my code, it was often downright impossible. I'm not suggesting that this be verbose, but at least a base minimum, which should also help to build the perception of professionalism. I'd see security and performance basics, perhaps, as optional extras though.

[froschdesign]

…should be a requirement.

The list from above contains already:

• elements that SHOULD to be present:
  • Unit Testing (in Cookbook)

This means to add descriptions how components like laminas-mail, laminas-form, laminas-form and so can be used in unit tests.

[settermjd]

Thanks for the feedback. Seems good to me.