Create Documentation-Principles.md

03-Purpose-and-Principles/Documentation-Principles.md

@@ -0,0 +1,90 @@
+# 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
+
+- *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 Organization Documentation Authors**: This project is intended to inform the authors of PureScript Organization Documentation, not PureScript Application Groups.
+
+## Documentation Scope
+
+- **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
+
+- **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 its primary terms.
+
+## 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.
+- **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 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
+
+- **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.
+- **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
+
+- 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, 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:
+    - 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.)
+
+## 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
+
+