diff options
| author | Sergio Carlavilla Delgado <carlavilla@FreeBSD.org> | 2022-03-26 10:07:04 +0000 |
|---|---|---|
| committer | Sergio Carlavilla Delgado <carlavilla@FreeBSD.org> | 2022-03-26 10:07:04 +0000 |
| commit | c38d26a740c0958e9158633f95947261eea59291 (patch) | |
| tree | 5d37cf30db78ffad5e9c0e05f4866c1e59d085f6 | |
| parent | 829192de8ad107621d1d2ce7cd45525e08e400a7 (diff) | |
| download | doc-c38d26a740c0958e9158633f95947261eea59291.tar.gz doc-c38d26a740c0958e9158633f95947261eea59291.zip | |
Add "role in ecosystem" to FDP Primer overview
Patch by: Pau Amma <pauamma_gundo.com>
Differential Revision: https://reviews.freebsd.org/D34486
| -rw-r--r-- | documentation/content/en/books/fdp-primer/overview/_index.adoc | 35 |
1 files changed, 35 insertions, 0 deletions
diff --git a/documentation/content/en/books/fdp-primer/overview/_index.adoc b/documentation/content/en/books/fdp-primer/overview/_index.adoc index bc2905f462..c8b7335a88 100644 --- a/documentation/content/en/books/fdp-primer/overview/_index.adoc +++ b/documentation/content/en/books/fdp-primer/overview/_index.adoc @@ -57,11 +57,46 @@ Willingness to contribute is the only membership requirement. This primer shows how to: +* Understand the role of documentation and its place in the ecosystem. * Identify which parts of FreeBSD are maintained by the FDP. * Install the required documentation tools and files. * Make changes to the documentation. * Submit changes back for review and inclusion in the FreeBSD documentation. +[[overview-documentation-ecosystem]] +== Documentation in the FreeBSD Ecosystem + +All documents are for the benefit of their readers, not their writers or caretakers. +They should adapt to the reader and not expect the reader to adapt to them. + +Never blame the reader for: + +* being unable to make use of a document easily or at all +* finding a document confusing +* not understanding a document or how to apply it +* not finding an explicit answer or successfully bridging gaps (or connecting dots) to reason their way to one + +Instead, acknowledge that the document is: + +* inaccessible +* confusing +* hard to understand or apply +* incomplete + +Then, make the document: + +* more accessible +* less confusing +* clearer +* more complete + +Use the following methods: + +* apply link:https://webaim.org/intro/#principles[accessibility best practices] to correct the problem reported and any similar ones you find +* rework or clarify the confusing structure or language +* add relevant examples to the part that is hard to understand or apply +* fill in the gaps or add the missing stepping stones + [[overview-quick-start]] == Quick Start |