From nobody Sat Mar 26 10:08:33 2022 X-Original-To: dev-commits-doc-all@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 990AA1A354E6 for ; Sat, 26 Mar 2022 10:08:35 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4KQZRR21v0z4YMZ; Sat, 26 Mar 2022 10:08:35 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1648289315; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=vBKhHjRoMhc03RMQZNtp89s+rB6vl6lHxmcUOhfQl6k=; b=ZO3/RO6CJtjvrFTqGz//kenFl5MaS0XCa9gMXzOkJBuU+ck0HcZIWhABwrI32ENfDYjwpF Cj4pWCP9XtlTeCr9ASA8uvzDD7Y/3xOhs2r7+227fyYSbH2VPgIU5S+o52wqeVCyWrdyv7 LM6EUgAy5O0WB3CYSqrfYKImKQpGcAWFdlAq9a7hescxhV+AwfnAOgyLLNrCoublHSfXe9 AXhFxyXMfFE3NLVdoqtx6uRATu8F9HE9MD8Zb1UGbWY0n/HZi469bHR9kcv2anN8k2I40D KnnXBcPOvmKxy+FutF+bOmtLbFJYH0FcvZxeSGzfXVbfq5lnXBzBrTVi06typw== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 0DB5B1EEA1; Sat, 26 Mar 2022 10:08:33 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.16.1/8.16.1) with ESMTP id 22QA8XD9079514; Sat, 26 Mar 2022 10:08:33 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 22QA8XfI079513; Sat, 26 Mar 2022 10:08:33 GMT (envelope-from git) Date: Sat, 26 Mar 2022 10:08:33 GMT Message-Id: <202203261008.22QA8XfI079513@gitrepo.freebsd.org> To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org From: Sergio Carlavilla Delgado Subject: git: c38d26a740 - main - Add "role in ecosystem" to FDP Primer overview List-Id: Commit messages for all branches of the doc repository List-Archive: https://lists.freebsd.org/archives/dev-commits-doc-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-dev-commits-doc-all@freebsd.org X-BeenThere: dev-commits-doc-all@freebsd.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: carlavilla X-Git-Repository: doc X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: c38d26a740c0958e9158633f95947261eea59291 Auto-Submitted: auto-generated ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1648289315; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=vBKhHjRoMhc03RMQZNtp89s+rB6vl6lHxmcUOhfQl6k=; b=nA47N5GBD8J+jDNEI2VwGRB9jftZJlmybpEvo++gjK+xkNF5rVKk+EcA0GSE9PP6DAGoZy xtfk5QDg+k/Ya0d+flNvIfVn5Dqcz4HqaWrFvrjdZrRyigipkkiK+xKydyKVOVoruhmUHV twQzRdk9SZ1vOeYIouehI4q2p/8gw/OUyZJWZ2ha0gllxTXC3bgqrMWOUlkdZsklKBToj+ A375J4Vvshuvp8cedpQZIgyCkYsMsaGvyLOVasrv0QDOfgqLHvwGKx6EoACOluGyfYw8Dc teK+orXvrZUQFL+wyxg9I886s7uspgq0TB+0j3hF1ljWjp5ARnI8QQ9QvI1MbA== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1648289315; a=rsa-sha256; cv=none; b=LmIVKXJgU3lDR+7XzJQFcoamZ3RKu32qtdstOK57yTGJ8ece6jzZ+8TWD/af9zMyrMgKgM 8NoNkKTfJeCoANigO8WnLqHJQxEUtz525w0luPoaHTM8o3CiAwtg4s/nt1OEEf3P8o8YTx EwV2Oa6R+SmSLruRVTY+16bXNjWgYEfukvideW57SLHij1jbvdNz3g2JSx3Qu6NMF3F5jZ jAHpx9nDDI/umSjfpi/aJui52gOF9BK4oAeg7R2ZMMWwWWmBhayXSmyDHKZdkC5oNknDxw uXynWVmc7iFNpr8RN8vVyU8hPa+xzjXrzc3ZTqVeYzfcWffcbqef80DqeakOUw== ARC-Authentication-Results: i=1; mx1.freebsd.org; none X-ThisMailContainsUnwantedMimeParts: N The branch main has been updated by carlavilla: URL: https://cgit.FreeBSD.org/doc/commit/?id=c38d26a740c0958e9158633f95947261eea59291 commit c38d26a740c0958e9158633f95947261eea59291 Author: Sergio Carlavilla Delgado AuthorDate: 2022-03-26 10:07:04 +0000 Commit: Sergio Carlavilla Delgado CommitDate: 2022-03-26 10:07:04 +0000 Add "role in ecosystem" to FDP Primer overview Patch by: Pau Amma 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