Create dev docs site
Description
We have various bits of documentation scattered around for developers (blog post, readme, contribute), but it's hard to find a good overview. The code/project can be very confusing and overwhelming for newcomers, and we end up doing a lot of explaining of the same things.
Also, as the code is not open source anything inside the repo is not available until the users have got access which complicates things.
Discussed with @inktrap a little bit, he said:
Since the project needs more developers, I think this is an important aspect. New developers would benefit from such a single, separate resource that is as simple and straightforward as possible. We could link to such a resource from the different foodsharing websites. Since I am new to the project and an active foodsharing.de user, I am happy to help with improving the documentation/info structure and communicating between the users and developers.
By answering my own questions I would get a better overview of the project and the project would get a fresh perspective. (Honestly, I did look around and I missed some things, some were obvious, some not.)
Proposal
A dev docs site!
I recently set one up for Karrot using gitbook.
So the idea would be:
- add
docs/
directory to foodsharing repo - make it a gitbook and add content
- build/publish the master branch to devdocs.foodsharing.de (or similar)
Content would include things like:
- general overview
- steps to contribute
- git process / workflow
- conventions we use
- testing guidelines
- ... maybe find a way to include the release notes (so it's public)
Links / references
- Readme https://gitlab.com/foodsharing-dev/foodsharing/blob/master/README.md
- Contributing guide https://gitlab.com/foodsharing-dev/foodsharing/blob/master/CONTRIBUTING.md
- Blog post https://devblog.foodsharing.de/2017/10/12/new-contributor-notes.html
- Karrot dev docs