docs: add and refine project documentation #41

Open

McPringle wants to merge 1 commit from McPringle/docs/add-project-documentation into main

McPringle commented

2026-05-02 17:45:47 +02:00

(Migrated from github.com)

Summary

This PR adds and restructures the repository documentation.

I noticed that the project did not have a README.md and that contributor-facing guidance was missing or incomplete, so I used this pass to build out the core documentation set and tighten the separation between public project information and contributor workflow.

What changed

added a new README.md
added a new CONTRIBUTING.md
replaced DOCKER.md with CONTAINERS.md
aligned the container documentation with both Docker and Podman usage
expanded .env.example so the available environment variables are documented more completely
cleaned up wording and overlap between the documentation files

Intent

The goal was to make the repository easier to understand for:

people discovering the project publicly
contributors who want to run, build, and test it locally
operators who want to run it in containers

I also tried to keep the responsibilities of the files clear:

README.md explains what the project is
CONTRIBUTING.md explains how to work on it
CONTAINERS.md explains container-based deployment and operation

Follow-up

I would also like to add three screenshots to the documentation:

Timeline
Analytics
Heatmap

I have not added them yet because I would first like to agree on where they should live in the repository.

Feedback wanted

I would especially appreciate feedback from @javahippie on:

whether this documentation structure and level of detail feels right for the project
where screenshots for the README should be stored
(my suggestion: docs/screenshots/)

## Summary This PR adds and restructures the repository documentation. I noticed that the project did not have a `README.md` and that contributor-facing guidance was missing or incomplete, so I used this pass to build out the core documentation set and tighten the separation between public project information and contributor workflow. ## What changed - added a new `README.md` - added a new `CONTRIBUTING.md` - replaced `DOCKER.md` with `CONTAINERS.md` - aligned the container documentation with both Docker and Podman usage - expanded `.env.example` so the available environment variables are documented more completely - cleaned up wording and overlap between the documentation files ## Intent The goal was to make the repository easier to understand for: - people discovering the project publicly - contributors who want to run, build, and test it locally - operators who want to run it in containers I also tried to keep the responsibilities of the files clear: - `README.md` explains what the project is - `CONTRIBUTING.md` explains how to work on it - `CONTAINERS.md` explains container-based deployment and operation ## Follow-up I would also like to add three screenshots to the documentation: - Timeline - Analytics - Heatmap I have not added them yet because I would first like to agree on where they should live in the repository. ## Feedback wanted I would especially appreciate feedback from @javahippie on: - whether this documentation structure and level of detail feels right for the project - where screenshots for the README should be stored (my suggestion: `docs/screenshots/`)

This pull request can be merged automatically.

You are not authorized to merge this pull request.

View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.

git fetch -u origin McPringle/docs/add-project-documentation:McPringle/docs/add-project-documentation

git checkout McPringle/docs/add-project-documentation

Merge

Merge the changes and update on Forgejo.

Warning: The "Autodetect manual merge" setting is not enabled for this repository, you will have to mark this pull request as manually merged afterwards.

git checkout main

git merge --no-ff McPringle/docs/add-project-documentation

git checkout McPringle/docs/add-project-documentation

git rebase main

git checkout main

git merge --ff-only McPringle/docs/add-project-documentation

git checkout McPringle/docs/add-project-documentation

git rebase main

git checkout main

git merge --no-ff McPringle/docs/add-project-documentation

git checkout main

git merge --squash McPringle/docs/add-project-documentation