git: c38d26a740 - main - Add "role in ecosystem" to FDP Primer overview
- Go to: [ bottom of page ] [ top of archives ] [ this month ]
Date: Sat, 26 Mar 2022 10:08:33 UTC
The branch main has been updated by carlavilla: URL: https://cgit.FreeBSD.org/doc/commit/?id=c38d26a740c0958e9158633f95947261eea59291 commit c38d26a740c0958e9158633f95947261eea59291 Author: Sergio Carlavilla Delgado <carlavilla@FreeBSD.org> AuthorDate: 2022-03-26 10:07:04 +0000 Commit: Sergio Carlavilla Delgado <carlavilla@FreeBSD.org> CommitDate: 2022-03-26 10:07:04 +0000 Add "role in ecosystem" to FDP Primer overview Patch by: Pau Amma <pauamma_gundo.com> Differential Revision: https://reviews.freebsd.org/D34486 --- .../en/books/fdp-primer/overview/_index.adoc | 35 ++++++++++++++++++++++ 1 file changed, 35 insertions(+) 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