Documentation

The structure of this documentation must follow the Diataxis Framework.

Diátaxis solves problems related to documentation content (what to write), style (how to write it) and architecture (how to organise it).

Structure

The documentation is structured in the following way:

• Explanations: explanations of the core features of the boilerplate, including the reasoning behind the choices we made. This are design philosophies, architecture choices, etc.
• Core Features: the core features included in the boilerplate, why we chose them, how to use them, how to remove them if not needed.
• Addons: guides to add features that are not part of the boilerplate, but are common enough to warrant a guide.
• Guides: “how-tos” use some included features in depth. Usually a guide covers a specific use case.
• References: reference documents, guidelines and best practices to follow when working with the codebase.
• Tutorials: in depth guides to create a specific feature, such as a CRUD entity, a feature module, etc.

Where to write documentation: Documentation app vs Readme vs Comments

In general, the documentation should be written in the Astro Documentation app, as to avoid duplication and keep the documentation up to date.

• Readme files should be as short as possible, and redirect to the Documentation app.
• Comments in the codebase are essential, as they auto documentation API (jsdoc) and are easier to update than the Documentation app (notably by LLMs, which will update the jsdoc as they refactor)
• The Documentation app should not duplicate API specifications already available in the source code. That means that in general, no API reference should be written in the Documentation app.

Language

For now, the documentation is written in English.