From f96d11b02e9115bd3711a27e8195361481d67e3f Mon Sep 17 00:00:00 2001 From: Alex Berg Date: Sun, 28 Apr 2019 11:43:58 -0500 Subject: [PATCH 01/15] Create Documentation-Principles.md --- 03-Purpose-and-Principles/Documentation-Principles.md | 8 ++++++++ 1 file changed, 8 insertions(+) create mode 100644 03-Purpose-and-Principles/Documentation-Principles.md diff --git a/03-Purpose-and-Principles/Documentation-Principles.md b/03-Purpose-and-Principles/Documentation-Principles.md new file mode 100644 index 0000000..368902d --- /dev/null +++ b/03-Purpose-and-Principles/Documentation-Principles.md @@ -0,0 +1,8 @@ +# Documentation principles + +- There are many types of applications that can be built with PureScript, each of which should have documentation. The group of people who write each type of application is best suited for managing its documentation. +- All types of PureScript applications have pre-requisite knowledge, and the set of this knowledge which is common across all PureScript applications should be managed by the group of PureScript groups, an entity which we will name the PureScript organization. + +- Documentation projects, and projects they depend on, are likely maintained by volunteers. We should appreciate contributions made by volunteers who find the time to contribute. If you're disappointed by a project's progress, you should try to find time to realize the change yourself and contribute it. If you need help contributing, ask for help in an issue or pull request on the project or in a PureScript user group. + +(Need to think about what other documentation principles there are. Group organization principles are also relevant.) From 77920685fb19a836bbe9b682741172ef97d341a9 Mon Sep 17 00:00:00 2001 From: Alex Berg Date: Sun, 28 Apr 2019 16:50:23 -0500 Subject: [PATCH 02/15] Categorize Documentation Principles and add more --- .../Documentation-Principles.md | 38 ++++++++++++++++++- 1 file changed, 36 insertions(+), 2 deletions(-) diff --git a/03-Purpose-and-Principles/Documentation-Principles.md b/03-Purpose-and-Principles/Documentation-Principles.md index 368902d..e646eff 100644 --- a/03-Purpose-and-Principles/Documentation-Principles.md +++ b/03-Purpose-and-Principles/Documentation-Principles.md @@ -1,8 +1,42 @@ -# Documentation principles +# Documentation Principles + +## Documentation Scope - There are many types of applications that can be built with PureScript, each of which should have documentation. The group of people who write each type of application is best suited for managing its documentation. - All types of PureScript applications have pre-requisite knowledge, and the set of this knowledge which is common across all PureScript applications should be managed by the group of PureScript groups, an entity which we will name the PureScript organization. -- Documentation projects, and projects they depend on, are likely maintained by volunteers. We should appreciate contributions made by volunteers who find the time to contribute. If you're disappointed by a project's progress, you should try to find time to realize the change yourself and contribute it. If you need help contributing, ask for help in an issue or pull request on the project or in a PureScript user group. +## Documentation Structure + +- Documentation is easiest to maintain if it follows a well-defined format. Templates offer a simple way of starting a new document. +- Documentation is easiest to maintain if it clearly defines its audience, its goal, and the primary terms it uses. + +## Documentation Content + +- *Some* documentation is better than no documentation. +- Documentation is easiest for a learner to navigate when its structure uses terms in the problem domain. Its content, then, is free to use terms in the solution domain. +- Documentation should avoid implicit bias towards a specific project as a solution. Instead, documentation should clearly explain the problem and only refer to specific projects in a list of implementations of the solution. While it's important to have a default recommended solution in a community, it's also important to give people freedom to add their own novel solutions to the ecosystem. + +## Documentation Audience + +- Documentation readers are expected to provide constructive feedback and improvements, provided they align with the goals and principles of the project. + +## Documentation Contributors + +- To encourage contributions, contributions should not be expected to be perfect. +- Documentation projects, and projects they depend on, are likely maintained by volunteers. We should appreciate contributions made by volunteers who find the time to contribute. If you need help contributing, ask for help in an issue or pull request on the project or in a PureScript user group. + +## Documentation Project Maintenance + +- A maintainer is expected to fulfill some responsibilities, as time allows: +-- Triage issues. +-- Respond to issues and contributions. +-- Make progress on resolving issues. +-- Find a new maintainer when they no longer want to be a maintainer. +- To become a maintainer, communicate with one of the existing maintainers, perhaps by opening an issue or commenting on an existing one. +- Some aspects to consider when deciding whether to accept a new maintainer: +-- They understand the principles of the project. +-- They have a stake in the project's success. +-- They have contributed a large amount to the project. + (Need to think about what other documentation principles there are. Group organization principles are also relevant.) From 1a67ad3d1586e74b102918f81d59bb897c73ef90 Mon Sep 17 00:00:00 2001 From: Alex Berg Date: Sun, 28 Apr 2019 16:52:26 -0500 Subject: [PATCH 03/15] Reformat sub-lists in principles. --- .../Documentation-Principles.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/03-Purpose-and-Principles/Documentation-Principles.md b/03-Purpose-and-Principles/Documentation-Principles.md index e646eff..443fe17 100644 --- a/03-Purpose-and-Principles/Documentation-Principles.md +++ b/03-Purpose-and-Principles/Documentation-Principles.md @@ -28,15 +28,16 @@ ## Documentation Project Maintenance - A maintainer is expected to fulfill some responsibilities, as time allows: --- Triage issues. --- Respond to issues and contributions. --- Make progress on resolving issues. --- Find a new maintainer when they no longer want to be a maintainer. + - Triage issues. + - Respond to issues and contributions. + - Make progress on resolving issues. + - Find a new maintainer when they no longer want to be a maintainer. + - To become a maintainer, communicate with one of the existing maintainers, perhaps by opening an issue or commenting on an existing one. - Some aspects to consider when deciding whether to accept a new maintainer: --- They understand the principles of the project. --- They have a stake in the project's success. --- They have contributed a large amount to the project. + - They understand the principles of the project. + - They have a stake in the project's success. + - They have contributed a large amount to the project. (Need to think about what other documentation principles there are. Group organization principles are also relevant.) From a1f37f59f33c73ee0300870277cbae1fc5b0c653 Mon Sep 17 00:00:00 2001 From: Alex Berg Date: Sun, 28 Apr 2019 16:56:49 -0500 Subject: [PATCH 04/15] Add qualifier to principles. --- 03-Purpose-and-Principles/Documentation-Principles.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/03-Purpose-and-Principles/Documentation-Principles.md b/03-Purpose-and-Principles/Documentation-Principles.md index 443fe17..616da8b 100644 --- a/03-Purpose-and-Principles/Documentation-Principles.md +++ b/03-Purpose-and-Principles/Documentation-Principles.md @@ -1,5 +1,7 @@ # Documentation Principles +These principles are not set in stone -- if you'd like clarification, qualification, addition, removal, or changes to these principles, open an issue to discuss. + ## Documentation Scope - There are many types of applications that can be built with PureScript, each of which should have documentation. The group of people who write each type of application is best suited for managing its documentation. From 993f628cf2faba4a34b5c2885e608d0a1b69044c Mon Sep 17 00:00:00 2001 From: Alex Berg Date: Sun, 28 Apr 2019 17:05:01 -0500 Subject: [PATCH 05/15] Rename 03-Purpose-and-Principles.md to 03-Purpose-and-Principles/ReadMe.md --- .../ReadMe.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename 03-Purpose-and-Principles.md => 03-Purpose-and-Principles/ReadMe.md (100%) diff --git a/03-Purpose-and-Principles.md b/03-Purpose-and-Principles/ReadMe.md similarity index 100% rename from 03-Purpose-and-Principles.md rename to 03-Purpose-and-Principles/ReadMe.md From 1e56dbb5d5d44ba9493297982b4f7b5a9530d53f Mon Sep 17 00:00:00 2001 From: Alex Berg Date: Sun, 28 Apr 2019 17:09:28 -0500 Subject: [PATCH 06/15] Narrow scope to PS organization in Principles --- 03-Purpose-and-Principles/Documentation-Principles.md | 1 + 1 file changed, 1 insertion(+) diff --git a/03-Purpose-and-Principles/Documentation-Principles.md b/03-Purpose-and-Principles/Documentation-Principles.md index 616da8b..2e5fef6 100644 --- a/03-Purpose-and-Principles/Documentation-Principles.md +++ b/03-Purpose-and-Principles/Documentation-Principles.md @@ -6,6 +6,7 @@ These principles are not set in stone -- if you'd like clarification, qualificat - There are many types of applications that can be built with PureScript, each of which should have documentation. The group of people who write each type of application is best suited for managing its documentation. - All types of PureScript applications have pre-requisite knowledge, and the set of this knowledge which is common across all PureScript applications should be managed by the group of PureScript groups, an entity which we will name the PureScript organization. +- The current scope of this project is the documentation managed by the PureScript organization. Other efforts can be responsible for documentation managed by PureScript groups. ## Documentation Structure From 57ce6075098759f9bf392e95c8778224ba4171cb Mon Sep 17 00:00:00 2001 From: Alex Berg Date: Sun, 28 Apr 2019 17:10:10 -0500 Subject: [PATCH 07/15] Narrow scope to PS organization in Principles From ef38c4a06726eb5b95ebcfb2fb96044587bcf8b2 Mon Sep 17 00:00:00 2001 From: Alex Berg Date: Sat, 4 May 2019 15:41:13 -0500 Subject: [PATCH 08/15] Move Documentation Authors out of Documentation Scope --- 03-Purpose-and-Principles/Documentation-Principles.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/03-Purpose-and-Principles/Documentation-Principles.md b/03-Purpose-and-Principles/Documentation-Principles.md index 2e5fef6..f9fb26f 100644 --- a/03-Purpose-and-Principles/Documentation-Principles.md +++ b/03-Purpose-and-Principles/Documentation-Principles.md @@ -2,10 +2,16 @@ These principles are not set in stone -- if you'd like clarification, qualification, addition, removal, or changes to these principles, open an issue to discuss. +## Documentation Authors + +- **PureScript Application Groups**: There are many types of applications which can be built with PureScript, and we call the group of people who create a type of application a PureScript application group. +- **PureScript Organization**: All PureScript applications have pre-requisite knowledge, and we call this group of people who maintain the facilities intended to benefit all PureScript applications the PureScript organization. +- **PureScript Organization Documentation**: The set of knowledge intended to benefit all PureScript applications is managed by the PureScript organization. +- **PureScript Application Documentation**: Each type of PureScript application should have documentation, and the group of people who write a type of application is best suited for managing its documentation. +- **This Project's Documentation Authors**: This scope of documentation authors this project is intended to improve and manage is PureScript Organization Documentation, not PureScript Application Documentation. + ## Documentation Scope -- There are many types of applications that can be built with PureScript, each of which should have documentation. The group of people who write each type of application is best suited for managing its documentation. -- All types of PureScript applications have pre-requisite knowledge, and the set of this knowledge which is common across all PureScript applications should be managed by the group of PureScript groups, an entity which we will name the PureScript organization. - The current scope of this project is the documentation managed by the PureScript organization. Other efforts can be responsible for documentation managed by PureScript groups. ## Documentation Structure From 9c3e6c21556f4f124721ca008dc431b0f4264fc3 Mon Sep 17 00:00:00 2001 From: Alex Berg Date: Sat, 4 May 2019 17:10:37 -0500 Subject: [PATCH 09/15] Create "Terms" section in Principles --- .../Documentation-Principles.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/03-Purpose-and-Principles/Documentation-Principles.md b/03-Purpose-and-Principles/Documentation-Principles.md index f9fb26f..919c883 100644 --- a/03-Purpose-and-Principles/Documentation-Principles.md +++ b/03-Purpose-and-Principles/Documentation-Principles.md @@ -2,17 +2,21 @@ These principles are not set in stone -- if you'd like clarification, qualification, addition, removal, or changes to these principles, open an issue to discuss. +## Terms + +- Documentation: The knowledge about a project stored in a written format, used to answer questions about the project. +- PureScript Application Groups: There are many types of applications which can be built with PureScript, and we call a group of people who creates one of these types of applications a PureScript application group. +- PureScript Organization: All PureScript applications have pre-requisite knowledge, and we call this group of people who maintain the facilities intended to benefit all PureScript applications the PureScript organization. +- PureScript Organization Documentation: The set of knowledge intended to benefit all PureScript applications is managed by the PureScript organization. +- PureScript Application Documentation: Each type of PureScript application should have documentation, and the group of people who write a type of application is best suited for managing its documentation. + ## Documentation Authors -- **PureScript Application Groups**: There are many types of applications which can be built with PureScript, and we call the group of people who create a type of application a PureScript application group. -- **PureScript Organization**: All PureScript applications have pre-requisite knowledge, and we call this group of people who maintain the facilities intended to benefit all PureScript applications the PureScript organization. -- **PureScript Organization Documentation**: The set of knowledge intended to benefit all PureScript applications is managed by the PureScript organization. -- **PureScript Application Documentation**: Each type of PureScript application should have documentation, and the group of people who write a type of application is best suited for managing its documentation. -- **This Project's Documentation Authors**: This scope of documentation authors this project is intended to improve and manage is PureScript Organization Documentation, not PureScript Application Documentation. +- **PureScript Organization Documentation Authors**: This project is intended to inform the authors of PureScript Organization Documentation, not PureScript Application Groups. ## Documentation Scope -- The current scope of this project is the documentation managed by the PureScript organization. Other efforts can be responsible for documentation managed by PureScript groups. +- **Knowledge Common to All PureScript Applications**: The current scope of this project is PureScript Organization Documentation. We expect other efforts to manage PureScript Application Groups Documentation. ## Documentation Structure From 30bb777a4ac6f1bd174c4b14baa77da170e8a374 Mon Sep 17 00:00:00 2001 From: Alex Berg Date: Sat, 4 May 2019 17:29:42 -0500 Subject: [PATCH 10/15] Restyle the principles --- .../Documentation-Principles.md | 26 +++++++++---------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/03-Purpose-and-Principles/Documentation-Principles.md b/03-Purpose-and-Principles/Documentation-Principles.md index 919c883..e0fd8a3 100644 --- a/03-Purpose-and-Principles/Documentation-Principles.md +++ b/03-Purpose-and-Principles/Documentation-Principles.md @@ -4,11 +4,11 @@ These principles are not set in stone -- if you'd like clarification, qualificat ## Terms -- Documentation: The knowledge about a project stored in a written format, used to answer questions about the project. -- PureScript Application Groups: There are many types of applications which can be built with PureScript, and we call a group of people who creates one of these types of applications a PureScript application group. -- PureScript Organization: All PureScript applications have pre-requisite knowledge, and we call this group of people who maintain the facilities intended to benefit all PureScript applications the PureScript organization. -- PureScript Organization Documentation: The set of knowledge intended to benefit all PureScript applications is managed by the PureScript organization. -- PureScript Application Documentation: Each type of PureScript application should have documentation, and the group of people who write a type of application is best suited for managing its documentation. +- *Documentation*: The knowledge about a project stored in a written format, used to answer questions about the project. +- *PureScript Application Groups*: There are many types of applications which can be built with PureScript, and we call a group of people who creates one of these types of applications a PureScript application group. +- *PureScript Organization*: All PureScript applications have pre-requisite knowledge, and we call this group of people who maintain the facilities intended to benefit all PureScript applications the PureScript organization. +- *PureScript Organization Documentation*: The set of knowledge intended to benefit all PureScript applications is managed by the PureScript organization. +- *PureScript Application Documentation*: Each type of PureScript application should have documentation, and the group of people who write a type of application is best suited for managing its documentation. ## Documentation Authors @@ -20,23 +20,23 @@ These principles are not set in stone -- if you'd like clarification, qualificat ## Documentation Structure -- Documentation is easiest to maintain if it follows a well-defined format. Templates offer a simple way of starting a new document. -- Documentation is easiest to maintain if it clearly defines its audience, its goal, and the primary terms it uses. +- **Well-defined Documentation Formats**: Documentation is easiest to maintain if it follows a well-defined format. Templates offer a simple way of starting a new document. +- **Clearly-defined Documentation Audience, Scope, and Terms**: Documentation is easiest to maintain if it clearly defines its audience, its goal, and the primary terms it uses. ## Documentation Content -- *Some* documentation is better than no documentation. -- Documentation is easiest for a learner to navigate when its structure uses terms in the problem domain. Its content, then, is free to use terms in the solution domain. -- Documentation should avoid implicit bias towards a specific project as a solution. Instead, documentation should clearly explain the problem and only refer to specific projects in a list of implementations of the solution. While it's important to have a default recommended solution in a community, it's also important to give people freedom to add their own novel solutions to the ecosystem. +- ***Some* Content is Better Than *No* Content**: There should be low barriers to creation of new documentation to encourage expansion of the knowledge repository. +- **Content Should be Addressable by Problem Domain**: Documentation is easiest for a learner to navigate when its structure uses terms in the problem domain. Its content, then, is free to use terms in the solution domain. +- **Content Should Teach, Not Prescribe**: Documentation should avoid implicit bias towards a specific project as a solution. Instead, documentation should clearly explain the problem and only refer to specific projects in a list of implementations of the solution. While it's important to have a default recommended solution in a community, it's also important to give people freedom to add their own novel solutions to the ecosystem. ## Documentation Audience -- Documentation readers are expected to provide constructive feedback and improvements, provided they align with the goals and principles of the project. +- **Audience Contributions Should be Encouraged**: Documentation readers are expected to provide constructive feedback and improvements, provided they align with the goals and principles of the project. ## Documentation Contributors -- To encourage contributions, contributions should not be expected to be perfect. -- Documentation projects, and projects they depend on, are likely maintained by volunteers. We should appreciate contributions made by volunteers who find the time to contribute. If you need help contributing, ask for help in an issue or pull request on the project or in a PureScript user group. +- **Contributions Need to be Adapted Rather than Filtered**: To encourage contributions, documentation maintainers should take ownership of new contributions after the change is proposed and before it is merged. Contributors are likely to be intimidated by the rigor and maintenance burden of crafting documentation which meets the standards of the project and are likely to be scared of contributing again in the future. +- **Clear Contribution Process and Policies**: Documentation projects, and projects they depend on, are likely maintained by volunteers. We should appreciate contributions made by volunteers who find the time to contribute. If you need help contributing, ask for help in an issue or pull request on the project or in a PureScript user group. ## Documentation Project Maintenance From d0d2d9a5429c14edb0a1995942d14c902330a519 Mon Sep 17 00:00:00 2001 From: Alex Berg Date: Sat, 4 May 2019 17:46:54 -0500 Subject: [PATCH 11/15] Revise two words' formatting --- 03-Purpose-and-Principles/Documentation-Principles.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/03-Purpose-and-Principles/Documentation-Principles.md b/03-Purpose-and-Principles/Documentation-Principles.md index e0fd8a3..dfc6f29 100644 --- a/03-Purpose-and-Principles/Documentation-Principles.md +++ b/03-Purpose-and-Principles/Documentation-Principles.md @@ -25,7 +25,7 @@ These principles are not set in stone -- if you'd like clarification, qualificat ## Documentation Content -- ***Some* Content is Better Than *No* Content**: There should be low barriers to creation of new documentation to encourage expansion of the knowledge repository. +- **_Some_ Content is Better Than _No_ Content**: There should be low barriers to creation of new documentation to encourage expansion of the knowledge repository. - **Content Should be Addressable by Problem Domain**: Documentation is easiest for a learner to navigate when its structure uses terms in the problem domain. Its content, then, is free to use terms in the solution domain. - **Content Should Teach, Not Prescribe**: Documentation should avoid implicit bias towards a specific project as a solution. Instead, documentation should clearly explain the problem and only refer to specific projects in a list of implementations of the solution. While it's important to have a default recommended solution in a community, it's also important to give people freedom to add their own novel solutions to the ecosystem. From 05da83fb2db8dc9af6f0f6817c2b79a9b705dabd Mon Sep 17 00:00:00 2001 From: Alex Berg Date: Sun, 5 May 2019 12:10:08 -0500 Subject: [PATCH 12/15] Add purpose of design of the principles --- 03-Purpose-and-Principles/Documentation-Principles.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/03-Purpose-and-Principles/Documentation-Principles.md b/03-Purpose-and-Principles/Documentation-Principles.md index dfc6f29..d4f2907 100644 --- a/03-Purpose-and-Principles/Documentation-Principles.md +++ b/03-Purpose-and-Principles/Documentation-Principles.md @@ -1,5 +1,7 @@ # Documentation Principles +These principles are intended to serve as the basic rules used when making judgements about the correctness of the documentation produced by this project. They are intended to serve a similar role of [axioms](https://en.wikipedia.org/wiki/Axiom) in a mathematics discipline. + These principles are not set in stone -- if you'd like clarification, qualification, addition, removal, or changes to these principles, open an issue to discuss. ## Terms From 63f5a6d6cb77f440e792eda30ff02c9ed463db8e Mon Sep 17 00:00:00 2001 From: Alex Berg Date: Sun, 5 May 2019 12:33:59 -0500 Subject: [PATCH 13/15] Add a basic Code of Conduct --- .../Documentation-Principles.md | 28 +++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/03-Purpose-and-Principles/Documentation-Principles.md b/03-Purpose-and-Principles/Documentation-Principles.md index d4f2907..35aa94d 100644 --- a/03-Purpose-and-Principles/Documentation-Principles.md +++ b/03-Purpose-and-Principles/Documentation-Principles.md @@ -56,3 +56,31 @@ These principles are not set in stone -- if you'd like clarification, qualificat (Need to think about what other documentation principles there are. Group organization principles are also relevant.) + +## Code of Conduct + +> A code of conduct empowers you to facilitate healthy, constructive community behavior. Being proactive reduces the likelihood that you, or others, will become fatigued with your project, and helps you take action when someone does something you don’t agree with. +> ~ https://opensource.guide/code-of-conduct/ + +The following constraints on conduct apply to members while they are actively participating in the PureScript Community, except as otherwise noted. + +To summarize the code into a single statement: We strive to treat every person with respect. + +Specifically, we aspire to these qualities: + +- We treat everyone with courtesy, aware that their diverse backgrounds, experiences, goals, and perspectives may be very different to ours. +- In our communication, we consistently honour and affirm the passion, professional expertise, and good intentions of others. Even if we occasionally doubt these qualities in someone else, we will not make public accusations of incompetence, malice or ulterior motives. +- We strive to be scrupulously polite at all times. There should be no rudeness, name-calling, or harassment in our communication. +- Where we disagree with someone, we avoid forms of expression that might make our dialogue partner feel attacked, humiliated, demeaned, or marginalised. Our critique should always be of specific statements and claims, never of people. +- Disagreement itself is fine: we are enriched by robust technical debate. But we seek to make the tone of that debate to be a conversation among people who respect, or even admire, each other. +- Where we disagree, we try to be curious about the perspective, goals, motivation, and priorities of the other person. +- We do not tolerate any form of discriminatory language or behaviour towards any minority (for example age, body size, disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation). +- We seek to apply these standards in all our public interactions in the PureScript Community sphere, including email, social media, discussion forums, and so on. + +If one of us fails to meet these standards, the ideal course of action is to write to that person privately, gently drawing attention to their lapse. If you're not comfortable with that, please contact the chair of the committee, or (if the chair is the problem) the vice-chair or co-chair. + +Our response should usually be to apologise and stop doing what it was that you are unhappy about. Even if we feel we have been misinterpreted or unfairly accused, the chances are good there was something we could have communicated better, and an apology is far more likely to bring healing than is a counter-accusation. + +https://github.com/ghc-proposals/ghc-proposals/blob/master/GRC.rst + + From 78ca28e3fe063e9015b21fd56f05b9b3e6248a65 Mon Sep 17 00:00:00 2001 From: Alex Berg Date: Sun, 12 May 2019 21:18:24 -0500 Subject: [PATCH 14/15] Revise "Teach, not Prescribe" --- 03-Purpose-and-Principles/Documentation-Principles.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/03-Purpose-and-Principles/Documentation-Principles.md b/03-Purpose-and-Principles/Documentation-Principles.md index 35aa94d..f5cad20 100644 --- a/03-Purpose-and-Principles/Documentation-Principles.md +++ b/03-Purpose-and-Principles/Documentation-Principles.md @@ -29,7 +29,7 @@ These principles are not set in stone -- if you'd like clarification, qualificat - **_Some_ Content is Better Than _No_ Content**: There should be low barriers to creation of new documentation to encourage expansion of the knowledge repository. - **Content Should be Addressable by Problem Domain**: Documentation is easiest for a learner to navigate when its structure uses terms in the problem domain. Its content, then, is free to use terms in the solution domain. -- **Content Should Teach, Not Prescribe**: Documentation should avoid implicit bias towards a specific project as a solution. Instead, documentation should clearly explain the problem and only refer to specific projects in a list of implementations of the solution. While it's important to have a default recommended solution in a community, it's also important to give people freedom to add their own novel solutions to the ecosystem. +- **Content Should Teach, Not Prescribe**: Documentation should guide the audience, not simply give an answser or prescribe a solution. While it's important to have a default solution in a community to recommend, it's also important to ensure people feel free to contribute new solutions to the ecosystem. ## Documentation Audience From da153888c121f922f4d5fe048f8194d1bdc88263 Mon Sep 17 00:00:00 2001 From: Alex Berg Date: Sun, 12 May 2019 21:45:05 -0500 Subject: [PATCH 15/15] Add principle about content editing --- 03-Purpose-and-Principles/Documentation-Principles.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/03-Purpose-and-Principles/Documentation-Principles.md b/03-Purpose-and-Principles/Documentation-Principles.md index f5cad20..0cb2804 100644 --- a/03-Purpose-and-Principles/Documentation-Principles.md +++ b/03-Purpose-and-Principles/Documentation-Principles.md @@ -23,7 +23,7 @@ These principles are not set in stone -- if you'd like clarification, qualificat ## Documentation Structure - **Well-defined Documentation Formats**: Documentation is easiest to maintain if it follows a well-defined format. Templates offer a simple way of starting a new document. -- **Clearly-defined Documentation Audience, Scope, and Terms**: Documentation is easiest to maintain if it clearly defines its audience, its goal, and the primary terms it uses. +- **Clearly-defined Documentation Audience, Scope, and Terms**: Documentation is easiest to maintain if it clearly defines its audience, its goal, and its primary terms. ## Documentation Content @@ -35,6 +35,10 @@ These principles are not set in stone -- if you'd like clarification, qualificat - **Audience Contributions Should be Encouraged**: Documentation readers are expected to provide constructive feedback and improvements, provided they align with the goals and principles of the project. +## Documentation Content Editing + +- **Policy-driven Content Editing**: To avoid frustrations originating from differing opinions of how content should be written, content editing should simply consist of enforcement of guidelines and policies, rather than judging the content on an ad-hoc basis. These guidelines and policies should be defined in a way such that judgements based on them are consistent. + ## Documentation Contributors - **Contributions Need to be Adapted Rather than Filtered**: To encourage contributions, documentation maintainers should take ownership of new contributions after the change is proposed and before it is merged. Contributors are likely to be intimidated by the rigor and maintenance burden of crafting documentation which meets the standards of the project and are likely to be scared of contributing again in the future. @@ -46,7 +50,7 @@ These principles are not set in stone -- if you'd like clarification, qualificat - Triage issues. - Respond to issues and contributions. - Make progress on resolving issues. - - Find a new maintainer when they no longer want to be a maintainer. + - Find a new maintainer, if possible, when they no longer want to be a maintainer. - To become a maintainer, communicate with one of the existing maintainers, perhaps by opening an issue or commenting on an existing one. - Some aspects to consider when deciding whether to accept a new maintainer: