From f6a5d1eaa9ba2f222afbdd8b4a8035e6055b224a Mon Sep 17 00:00:00 2001 From: KemoNine Date: Thu, 11 Oct 2018 15:27:25 -0400 Subject: [PATCH] Add additional info for documentation contributions --- contributing/CONTRIBUTING.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/contributing/CONTRIBUTING.md b/contributing/CONTRIBUTING.md index 65d00f5..4dfadbd 100644 --- a/contributing/CONTRIBUTING.md +++ b/contributing/CONTRIBUTING.md @@ -16,3 +16,19 @@ If you already have code or documentation to contribute, our [documentation repo Lowering the barrier for contributions is important: we value your input, regardless of your level of experience or area of expertise. If you would rather [contact us directly (link)](https://lollipopcloud.solutions/page/contact/), please do not hesitate to reach out through email or chat. We can also provide assistance walking you through our contribution process if you'd like to learn SOSASA or Gitea. Note: by submitting a PR, you agree to your contribution(s) being licensed as described in our [LICENSE.md (link)](LICENSE.md). + +## Documentation + +**In order to ease up the process of reading and applying docs, please:** + +* Add an intro to what the documentation is about (a couple of paragraphs should suffice) before presenting links, code, etc., for the sake of context - especially to the non-initiated; +* Make very clear what each step is and use language that anyone would understand (KISS); +* Don't abbreviate or assume something is banal/easy/common knowledge; +* Be specific even when it sounds like it's something everyone knows about. + Example of something that should be specified in docs: where to implement the stuff you just wrote about; + +**For extra readability purposes:** + +* Use markdown, if possible, for different areas/topics among the doc (text vs code, for example), as well as space; +* Break apart config/commands from docs. +* If you can't explain a "basic concept" in a easy way without making a wall of text in the middle of your doc, feel free to hyperlink to other documentation where those concepts are already explained, be it Wikipedia or another doc online that has high readability and reliability;