From 8578c20d85a0800aff6fb0226b13b291c0336950 Mon Sep 17 00:00:00 2001 From: Graham Johnson Date: Thu, 31 Aug 2023 16:06:43 -0400 Subject: [PATCH 1/3] Add change log documentation to readme --- wiki/_README.md | 126 ++++++++++++++++++++++++++++++++++++------------ 1 file changed, 96 insertions(+), 30 deletions(-) diff --git a/wiki/_README.md b/wiki/_README.md index fa9308c6519..b3bcd38e295 100644 --- a/wiki/_README.md +++ b/wiki/_README.md @@ -1,65 +1,131 @@ -_Certified fresh 230808 by Graham Johnson._ +**Contents** +- [Navigating The Docs](#navigating-the-docs) +- [Updating The Docs: How & When](#updating-the-docs-how--when) + * [Documentation Language](#documentation-language) + + [Indexicality & Timestamps](#indexicality--timestamps) + + [Must, Should, & May](#must-should--may) +- [Tracking Documentation Status](#tracking-documentation-status) + * [Change Logs](#change-logs) + + [Example Change Log](#example-change-log) + + [Change Log Keyphrases](#change-log-keyphrases) + - [Authored By](#authored-by) + - [Certified Fresh By](#certified-by) + - [Flagged By](#flagged-by) + - [Merged By](#merged-by) + - [Split Off By](#split-off-by) + - [Updated By](#updated-by) +- [Change Log](#change-log) + + # Navigating the docs -For a complete list of entries, see our [Table of Contents](_TOC.md) +For a complete list of wiki entries, see our [Table of Contents](_TOC.md) -# Updating the docs: How & when +# Updating The Docs: How & When -Whenever a code change PR breaks (or makes obsolete) existing documentation, the relevant entry should be updated. This documentation update should be included within the PR itself, similar to how one would update unit tests alongside a breaking code change. +Whenever a code-change PR breaks (or makes obsolete) existing documentation, the relevant entry should be updated. This documentation update should be included within the PR itself, similar to how one would update unit tests alongside a breaking code change. -Similarly, whenever a PR adds codebase functionality where either: +Similarly, whenever a PR _adds_ codebase functionality where either... 1. accompanying documentation has been explicitly requested 2. the implementing engineer believes the new functionality will not be easily legible to or extendable by future engineers -...then that PR should include a new documentation entry as part of its purview. +...then that PR should include documentation as part of its purview. + +Significant updates to wiki entries should be manually listed in a given entry's change log; see the [Change Log](#change-log) sub-entry for guidelines and context. All entries should follow the [Documentation Language](#documentation-language) guidelines. + +At least for the duration of 2023, as we implement this new system, any PR that updates or contributes to our documentation wiki should tag @gdjohnson (the documentarian) on GitHub. + +## Documentation Language + +### Indexicality & Timestamps -At least for the duration of 2023, as we implement this new system, any PR that updates or contributes to our documentation wiki should tag @gdjohnson (the documentarian) on Github. +Language is "indexical" insofar as it relies on inferred context to be understood. For instance, in our wiki, words like "I," "you," "now," and "soon" are indexical insofar as they rely on a context, known to the contributor at time of writing, that will likely be lost to future readers. -# Documentation language +In place of pronouns, documentation should be written with proper names and nouns. Moreover, it is preferable to name _teams_ rather than individuals _on_ teams, since individuals may be replaced or change over time. -## Must, Should, & May +References to places and times (e.g. "now," "soon," "recently," "historically") should be explicitly contextualized with dates whenever possible (e.g. "As of 230831..."). Dates across our wiki and codebase should be structured YYMMDD, e.g. 230831 for August 31st, 2023. + +### Must, Should, & May Per [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119), the following prescriptive language should be consistently used across documentation in order to specify the strength of given guideliens or requirements: 1. **MUST**: This word, or the term "REQUIRED," conveys that the definition is an absolute requirement of the specification. 2. **MUST NOT**: This phrase conveys that the definition is an absolute prohibition of the specification. 3. **SHOULD**: This word, or the adjective "RECOMMENDED", conveys that there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications must be understood and carefully weighed before choosing a different course. -4. **SHOULD NOT** This phrase, or the phrase "NOT RECOMMENDED" conveys that there may exist valid reasons in particular circumstances when the particular behavior is acceptable or even useful, but the full implications should be understood and the case carefully weighed before implementing any behavior described with this label. -5. **MAY** This word, or the adjective "OPTIONAL", mean that an item is truly optional. +4. **SHOULD NOT**: This phrase, or the phrase "NOT RECOMMENDED" conveys that there may exist valid reasons in particular circumstances when the particular behavior is acceptable or even useful, but the full implications should be understood and the case carefully weighed before implementing any behavior described with this label. +5. **MAY**: This word, or the adjective "OPTIONAL", mean that an item is truly optional. -# Tracking documentation status +# Tracking Documentation Status An important part of maintaining a working documentation system involves flagging (1) areas in need of documentation (2) areas whose documentation has gone stale. -For now, the best system is notifying the archivist, Graham Johnson, on Slack or Github (@gdjohnson). Down the line, a more structured system may be worth implementing. +As of 230831, the best system for flagging stale and missing documentation is by either (1) notifying the archivist, Graham Johnson, on Slack or Github, or (2) adding to our [documentation wishlist](./_Wishlist.md). Down the line, a more structured system may be implemented. + +## Change Logs + +Our git history has been frequently compromised across the history of the codebase, and is not fully reliable. Moreover, git history omits documentation audits and conflates local. and page-wide updates. + +In order to track the history and status of documentation (e.g. to determine whether it is "fresh" or "stale"), we're introducing manual change logs at the bottom of each entry, under an H1 header. Change logs should record the following actions: +- Page authorship ("Authored by") +- Significant rewrites, either of the entire entry, or dedicated sections ("Updated by") +- Merges and branchings ("Merged by," "Split off by") +- Audits and certifications ("Certified fresh by") +- Flagging sections as incomplete, unclear, misleading, or out of date ("Flagged by") + +Change log entries _should_ center around one of the default change log keyphrases, [listed below](#change-log-keyphrases). They _should_ include additional useful context, including any relevant PRs, and _must_ name the individual responsible for the action as well as the date the action occurred. + +When an engineer visits a documentation entry for the first time, the Change Log should be the first section checked. Is the entry out of date? Has it been flagged for an overhaul? One goal of the Change Log is to prevent engineers from wasting time implementing obsolete documentation. A second goal is to ensure engineers, when assigned work in novel areas of the codebase, are guaranteed adequate documentation for onboarding into that area. + +### Example Change Log + +```md +# Change Log + +- 230506: Updated and certified fresh by Jane Doe, in light of API changes (#3150). +- 230403: Flagged by John Smith; will likely fall out of date with upcoming API changes. +- 221201: Certified fresh by Jane Doe. +- 220507: Authored by John Smith (#2350). +``` + +### Change Log keyphrases + +#### Authored By + +Initial authorship. Ideally, all newly authored documentation should also be [certified fresh](#certified-fresh), and authorship on a given date should be assumed to be synonymous with certification on that date. However, as of 230831, we should specifically list certification alongside the author log, to guarantee this standard of quality. + +#### Certified Fresh By + +When a contributor certifies an entry as fresh, he is attesting that he has successfully tested, or else followed/implemented/executed, the entry on a given date. For process documentation (e.g. [Ways of Working](./Ways-Of-Working.md)), an entry is certified fresh when an authorized individual has reviewed and signed-off the entry's guidelines. + +A contributor _may_ certify either a full entry, or a section of that entry, as fresh. But it is important not to certify a wider scope than has been actually verified as accurate. Certification is meant to be a strong signal to engineers, in using documentation, that the documentation can be relied-upon as up-to-date and accurate. Dilution of the certification system is more harmful than a lack of certification. + +The other purpose of certification is to provide an additional contact, so that users of the documentation can reach out with questions or comments. + +All newly added pages or sections in the wiki should be explicitly certified to the date of their addition, as it is assumed that all new documentation should meet the above criteria. -## "Certified fresh" datestamps +#### Flagged By -Moving forward, our goal is to keep a “Certified fresh” datestamp on all wiki entries. This timestamp is accompanied by an optional note and the name of the certifier. For consistency, dates should take the format YYMMDD. +If an engineer is using or auditing the docs, and notices an incomplete, out-of-date, or misleading entry, this should be explicitly flagged. -Example certification: -> _Certified fresh 230731 by Graham Johnson._ -> _Note: The optional super-admin steps listed under the "Verifying addresses" sub-section were not re-tested and may be stale._ +Any concerns about future reliability of the entry (e.g. an engineer knows that in a few months, a new technical solution will replace the currently documented solution) should be noted here whenever possible. -### What does “Certified fresh” mean operationally? +The goal of the "Flagged by" keyphrase is to raise awareness about which areas of the wiki need attention, and to prevent future engineers from implementing misleading or out-of-date instructions. -1. "Certified fresh on X date" means that an engineer or documentarian has successfully tested or followed the entry’s documentation on X date. -2. Successfully acting upon a few tidbits of information on an entry page for development guidance is not sufficient to certify an entry. -3. "Certified fresh" is a _strong recommendation_ from the certifying team member that the documentation can be faithfully followed. -4. All newly added pages or sections in the wiki should be explicitly certified to the date of their addition, as it is assumed that all new documentation should meet the above criteria (#s 1-3). +#### Merged By -### Certification notes & elaboration +If pages are merged together, this should be noted in the change log of the merged-into page, and a compressive summary of the merged page provided below. -Any additional information (e.g. caveats, conditionals, environmental details that might make the certification partial or provisional) should be added as a note under the datestamp. +#### Split Off By -If only a sub-section can be certified fresh, that section should be explicitly noted. The same is true of any sub-sections that should be excluded from the certification (e.g. that the certifier cannot vouch for, has been unable to test, etc). +If a section is moved out of one entry and into another, this should be listed explicitly in the change logs, so that engineers who have come to rely on the section's previous location are able to find it. -Any concerns about future reliability of the entry (e.g. the certifying engineer knows that in a few months, a new technical solution will replace the currently documented solution) should be noted here if possible. +#### Updated By -## Certifying: When & how +Used for all significant updates, or changes of note. -All certifications (new or updated) should be either (1) submitted in the larger PR in which the documentation entry was certified fresh (2) be opened as a separate PR. +# Change Log -At least for the duration of 2023, as we implement this new system, all certifications and additions to documentation should tag/flag @gdjohnson (the documentarian) on Github +230831: Updated and certified fresh by Graham Johnson (#). +230808: Authored by Graham Johnson. \ No newline at end of file From c9598acb7009420fd498ece1969601663426070c Mon Sep 17 00:00:00 2001 From: Graham Johnson Date: Thu, 31 Aug 2023 16:07:23 -0400 Subject: [PATCH 2/3] Change log tweaks --- wiki/_README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/wiki/_README.md b/wiki/_README.md index b3bcd38e295..c18fbc75a64 100644 --- a/wiki/_README.md +++ b/wiki/_README.md @@ -127,5 +127,5 @@ Used for all significant updates, or changes of note. # Change Log -230831: Updated and certified fresh by Graham Johnson (#). -230808: Authored by Graham Johnson. \ No newline at end of file +- 230831: Updated and certified fresh by Graham Johnson. +- 230808: Authored by Graham Johnson. \ No newline at end of file From f3aa33da0bc992f85c071da678de5a97df648151 Mon Sep 17 00:00:00 2001 From: Graham Johnson Date: Fri, 1 Sep 2023 11:50:44 -0400 Subject: [PATCH 3/3] Second pass --- wiki/_README.md | 54 ++++++++++++++++++++++++------------------------- 1 file changed, 27 insertions(+), 27 deletions(-) diff --git a/wiki/_README.md b/wiki/_README.md index c18fbc75a64..d4e9b4510c1 100644 --- a/wiki/_README.md +++ b/wiki/_README.md @@ -16,20 +16,18 @@ - [Updated By](#updated-by) - [Change Log](#change-log) - - # Navigating the docs For a complete list of wiki entries, see our [Table of Contents](_TOC.md) # Updating The Docs: How & When -Whenever a code-change PR breaks (or makes obsolete) existing documentation, the relevant entry should be updated. This documentation update should be included within the PR itself, similar to how one would update unit tests alongside a breaking code change. +Whenever engineering work makes existing documentation obsolete, relevant entries should be updated. This documentation update should be included within the PR itself, similar to how one would update unit tests alongside a breaking code change. -Similarly, whenever a PR _adds_ codebase functionality where either... +Similarly, whenever a PR introduces new codebase functionality where either... -1. accompanying documentation has been explicitly requested -2. the implementing engineer believes the new functionality will not be easily legible to or extendable by future engineers +1. accompanying documentation has been explicitly requested +2. the implementing engineer believes the new functionality will not be easily comprehensible future engineers ...then that PR should include documentation as part of its purview. @@ -43,7 +41,7 @@ At least for the duration of 2023, as we implement this new system, any PR that Language is "indexical" insofar as it relies on inferred context to be understood. For instance, in our wiki, words like "I," "you," "now," and "soon" are indexical insofar as they rely on a context, known to the contributor at time of writing, that will likely be lost to future readers. -In place of pronouns, documentation should be written with proper names and nouns. Moreover, it is preferable to name _teams_ rather than individuals _on_ teams, since individuals may be replaced or change over time. +In place of pronouns, documentation should be written with proper names and nouns. Moreover, it is preferable to name _teams_ rather than individuals, since individuals may be replaced or change over time. References to places and times (e.g. "now," "soon," "recently," "historically") should be explicitly contextualized with dates whenever possible (e.g. "As of 230831..."). Dates across our wiki and codebase should be structured YYMMDD, e.g. 230831 for August 31st, 2023. @@ -61,29 +59,29 @@ Per [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119), the following prescripti An important part of maintaining a working documentation system involves flagging (1) areas in need of documentation (2) areas whose documentation has gone stale. -As of 230831, the best system for flagging stale and missing documentation is by either (1) notifying the archivist, Graham Johnson, on Slack or Github, or (2) adding to our [documentation wishlist](./_Wishlist.md). Down the line, a more structured system may be implemented. +As of 230901, the best system for flagging stale and missing documentation is by either (1) notifying the archivist, Graham Johnson, on Slack or Github (@gdjohnson), or (2) adding to our [documentation wishlist](./_Wishlist.md). Down the line, a more structured system may be needed. ## Change Logs -Our git history has been frequently compromised across the history of the codebase, and is not fully reliable. Moreover, git history omits documentation audits and conflates local. and page-wide updates. +Our git history has been frequently compromised across the history of the codebase, and is not fully reliable. Moreover, git history omits documentation audits and conflates minor local changes with noteworthy, page-wide updates. -In order to track the history and status of documentation (e.g. to determine whether it is "fresh" or "stale"), we're introducing manual change logs at the bottom of each entry, under an H1 header. Change logs should record the following actions: -- Page authorship ("Authored by") -- Significant rewrites, either of the entire entry, or dedicated sections ("Updated by") -- Merges and branchings ("Merged by," "Split off by") -- Audits and certifications ("Certified fresh by") -- Flagging sections as incomplete, unclear, misleading, or out of date ("Flagged by") +In order to track the history and status of documentation (e.g. to determine whether an entry is "fresh" or "stale"), we're introducing manual change logs. Change logs must be placed at the bottom of each entry, under an H1 header. Change logs should record the following actions: +- Page authorship (using the keyphrase "Authored by") +- Significant rewrites, either of the entire entry, or dedicated sections (using the keyphrase "Updated by") +- Merges and branchings (using the keyphrases "Merged by," "Split off by") +- Audits and certifications (using the keyphrase "Certified fresh by") +- Flagging sections as incomplete, unclear, misleading, or out of date (using the keyphrase "Flagged by") -Change log entries _should_ center around one of the default change log keyphrases, [listed below](#change-log-keyphrases). They _should_ include additional useful context, including any relevant PRs, and _must_ name the individual responsible for the action as well as the date the action occurred. +Change log entries should center around one of the default change log keyphrases, [listed below](#change-log-keyphrases). They should include additional useful context, including any relevant PRs, and must name the individual responsible for the action as well as the date the action occurred. -When an engineer visits a documentation entry for the first time, the Change Log should be the first section checked. Is the entry out of date? Has it been flagged for an overhaul? One goal of the Change Log is to prevent engineers from wasting time implementing obsolete documentation. A second goal is to ensure engineers, when assigned work in novel areas of the codebase, are guaranteed adequate documentation for onboarding into that area. +The change log should often be the first section of a wiki entry checked. Is the entry out of date? Has it been flagged for an overhaul? One goal of change logs is to prevent engineers from wasting time implementing obsolete documentation. A second goal is to ensure engineers, when assigned work in novel areas of the codebase, can be guaranteed adequate documentation for onboarding into that area. ### Example Change Log ```md # Change Log -- 230506: Updated and certified fresh by Jane Doe, in light of API changes (#3150). +- 230606: Updated and certified fresh by Jane Doe, in light of API changes (#3150). - 230403: Flagged by John Smith; will likely fall out of date with upcoming API changes. - 221201: Certified fresh by Jane Doe. - 220507: Authored by John Smith (#2350). @@ -93,17 +91,19 @@ When an engineer visits a documentation entry for the first time, the Change Log #### Authored By -Initial authorship. Ideally, all newly authored documentation should also be [certified fresh](#certified-fresh), and authorship on a given date should be assumed to be synonymous with certification on that date. However, as of 230831, we should specifically list certification alongside the author log, to guarantee this standard of quality. +The author responsible for creating the entry. Since new wiki pages should only be created ~fully formed (i.e. no stubs or placeholders), the author will in most cases also be the individual with most knowledge of the area affected, or who is taking on some level of responsibility for the page's content. + +Ideally, all newly authored documentation should also be [certified fresh](#certified-fresh), and authorship on a given date should be assumed to be synonymous with certification on that date. However, as of 230901, we should specifically include the "certified fresh" keyphrase alongside the "authored by" entry, to guarantee this standard of quality. #### Certified Fresh By -When a contributor certifies an entry as fresh, he is attesting that he has successfully tested, or else followed/implemented/executed, the entry on a given date. For process documentation (e.g. [Ways of Working](./Ways-Of-Working.md)), an entry is certified fresh when an authorized individual has reviewed and signed-off the entry's guidelines. +When a contributor certifies an entry as fresh, he is attesting that he has successfully tested, or else followed (implemented, executed), the entry on a given date. For non-codebase process documentation (e.g. [Ways of Working](./Ways-Of-Working.md)), an entry is certified fresh when an authorized individual (typically a lead) has reviewed and signed off on an entry's guidelines. -A contributor _may_ certify either a full entry, or a section of that entry, as fresh. But it is important not to certify a wider scope than has been actually verified as accurate. Certification is meant to be a strong signal to engineers, in using documentation, that the documentation can be relied-upon as up-to-date and accurate. Dilution of the certification system is more harmful than a lack of certification. +All newly added pages or sections in the wiki should be explicitly certified to the date of their addition, as it is assumed that all new documentation meets the above criteria. -The other purpose of certification is to provide an additional contact, so that users of the documentation can reach out with questions or comments. +A contributor may certify either a full entry, or a section of that entry, as fresh. But it is important not to certify a wider scope than has been actually verified as accurate. Certification is meant to be a strong signal to engineers, in using documentation, that the documentation can be relied upon as up-to-date and accurate. Dilution of the certification system is more harmful than a lack of certification. -All newly added pages or sections in the wiki should be explicitly certified to the date of their addition, as it is assumed that all new documentation should meet the above criteria. +The other purpose of certification is to provide an additional contact, so that users of the documentation can reach out with questions or comments. (Authors are typically assumed to be the primary contact for entries.) #### Flagged By @@ -111,11 +111,11 @@ If an engineer is using or auditing the docs, and notices an incomplete, out-of- Any concerns about future reliability of the entry (e.g. an engineer knows that in a few months, a new technical solution will replace the currently documented solution) should be noted here whenever possible. -The goal of the "Flagged by" keyphrase is to raise awareness about which areas of the wiki need attention, and to prevent future engineers from implementing misleading or out-of-date instructions. +The goal of the "Flagged by" keyphrase is to raise awareness of areas of the wiki need attention, and to prevent future engineers from implementing misleading or out-of-date instructions. #### Merged By -If pages are merged together, this should be noted in the change log of the merged-into page, and a compressive summary of the merged page provided below. +If pages are merged together, this should be noted in the change log of the merged-into page, and a compressive summary of the merged page should be provided below. #### Split Off By @@ -123,9 +123,9 @@ If a section is moved out of one entry and into another, this should be listed e #### Updated By -Used for all significant updates, or changes of note. +Used for all significant updates or changes of note. This helps flag, for engineers who may have recently used a docs entry, that some load-bearing aspect of documentation has changed. # Change Log -- 230831: Updated and certified fresh by Graham Johnson. +- 230831: Updated and certified fresh by Graham Johnson (#4941). - 230808: Authored by Graham Johnson. \ No newline at end of file