diff options
authorSergio Carlavilla Delgado <carlavilla@FreeBSD.org>2022-03-26 10:07:04 +0000
committerSergio Carlavilla Delgado <carlavilla@FreeBSD.org>2022-03-26 10:07:04 +0000
commitc38d26a740c0958e9158633f95947261eea59291 (patch)
parent829192de8ad107621d1d2ce7cd45525e08e400a7 (diff)
Add "role in ecosystem" to FDP Primer overview
Patch by: Pau Amma <pauamma_gundo.com> Differential Revision: https://reviews.freebsd.org/D34486
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.
+== 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
== Quick Start