Let's Discuss Improving Documentation and Styling Guidelines To Help New and Old Contributors

Development
3

during the application preparation process I collect some reference for improving the documentation.
You can split them in three groups

  1. code structure

    1. I wouldn’t mind if we start do create a graph on draw.io to visualize it nicely. Mattermost is a good example: https://docs.mattermost.com/overview/architecture.html

  2. how to code:

    1. tell what IDE etc. to use. You don’t have to explain it, a numbered steps list, referencing to the relevant doc section would be sufficient. We all know that reading through all the docs isn’t fun, e.g. recent case GSoC2020- Intoduction to community.
      That could be tackled by saying:

      1. get React Native as explained in
      2. apply these settings
      3. get a simulator as explained here

      or in case git

      1. get git CL version, other tools with GUI we can recommend are … but we won’t support for technical question
      2. do clone, pull etc. as described in …
      3. …

      some suggestion might be obviously, some might “if you want to code, you should know that” but in the end is all about lowering the entry barrier!
      Discourse doing it quite well: https://meta.discourse.org/t/discourse-development-contribution-guidelines/3823

  3. Contribution Guidelines

    1. an example with a lot of text, rather generic: https://zulip.readthedocs.io/en/latest/contributing/version-control.html#commit-discipline

    2. same here but review and additional resources section is good read:
      https://zulip.readthedocs.io/en/latest/contributing/code-reviewing.html#additional-resources
      A real pearl is their tool collection for visualizing the benefit of a PR:
      https://zulip.readthedocs.io/en/latest/tutorials/screenshot-and-gif-software.html
      Moreover they put a lot of effort visualizing the coding style:
      https://zulip.readthedocs.io/en/latest/contributing/code-style.html

    3. same for rocket.chat:
      https://github.com/RocketChat/docs/tree/master/developer-guides/code-styleguide/less

    4. and nextcloud:
      https://docs.nextcloud.com/server/latest/developer_manual/general/codingguidelines.html

have look what was criticized in the GSoC realted PRs: https://github.com/laurent22/joplin/pulls?utf8=✓&q=is%3Apr+label%3Agsoc-2020+

my idea is to apply for GSoC to get that done/supported by a student.
As many docs are on readthedocs.io what integrate nicely wiht GitHub Joplin doc may moves there as well.

1 Like