Create Documentation-Principles.md

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

@@ -0,0 +1,46 @@
+# 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.
+- 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
+
+- 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.)