Documentation improvement to reduce verbosity and visual span

[brunolnetto]

First of all, congratulations 🥳 ! This is by far the best repository I have seen in a long time. I really expected to have something similar while developing my first FastAPI boilerplate.

My suggestion may sound somewhat junior-level, please, do not judge me. BUT I like to have changes and actions STRICTLY CLEAR, which your documentation succeeds, in a verbose mode, which maybe well for someone with more experience. Do not take me wrong, but this repository would benefit from collapsable components to summarize the documentation, like I helped with here, particularly this page. Also, explicit citations on where to perform customization, like the cookiecutter.json, pointers of what to read and why for the very beginning is very appreciated (these instructions appears on advanced mathematics textbooks).

I can suggest my own changes as a pull request if you like, but I need your thumbs up first.

Take a look at my fork repo:

1. Main README https://github.com/trouchet/full-stack-fastapi-postgresql
2. Project README: https://github.com/trouchet/full-stack-fastapi-postgresql/blob/master/%7B%7Bcookiecutter.project_slug%7D%7D/README.md

Anyhow, once more CONGRATULATIONS AND THANKS FOR THIS REPOSITORY! 🥳

[turukawa]

Hi @brunolnetto thanks for the comments, and I'm always happy to have help on documentation.

You'll see I've offloaded most of the documentation to this folder where I tend to keep it much more up-to-date than the readme's. https://github.com/whythawk/full-stack-fastapi-postgresql/tree/master/docs

The "source of truth" will always be these docs first, with me frequently forgetting the generated readme's (front- and backends).

At some stage, when I have time, I'll be upgrading to Pydantic 2.0, and then the documentation may need to change again (not too sure what the implications are to the stack). Plus, I'm also considering whether I should integrate i18n directly through the stack. I'm busy with a project that requires static and dynamic i18n, and the complexity is sufficient to think it may be useful to others to have a base project with that demonstrated.

Anyway, safe to say that the stack documentation could do with a review from someone else with a better eye to what less experienced FastAPI developers may need.

Thanks ...

[brunolnetto]

Among ideas, there is cartographic map or summary of the solution. For example, cite which libraries were used for:

1. Module development libraries;
2. Backend part;
3. Frontend part;

For each of topics above, cite what was placed where. It will give the future developer YOUR glimpse of how the libraries work together and what you thought while developing the project.

Also, a refactor stage is welcome based on reading of old README.md files on root and {{cookiecutter.project_slug}}. After it, I recommend to erase the old ones. This anew structure will require the above summary, or some reading order to guide the reader.

[brunolnetto]

Update:

I made as requested on docs/development-quide.md for development. The configuration setup requires some meta categories:

• project;
• domain;
• docker_swarm;
• totp;
• smtp;
• postgres;
• pgadmin;
• neo4j;
• traefik;
• flower;
• sentry;
• docker_image.

Since my own ignorance, I am unaware of some above. I came up to some suggestions, if you may implement them:

1. The required information tagged as totp is missing on documentation;
2. Consider adding some links or tutorials to smtp;
3. I noticed the below domains follow the same default values: it suggests removing either one or the other to reduce extra-configuration;

main: domain_main, traefik_constraint_tag
staging: domain_staging, traefik_constraint_tag_staging

4. Will pgadmin related information make me able to perform database privilege modifications, right?
5. The docker_image-related configurations seems too much customization IMHO;

I have never used docker_swarm, neo4j, traefik, flower, sentry. Which means, I will need either your help or further reading.

Thanks for your work, again!

[turukawa]

Hey @brunolnetto sorry, haven't forgotten, just been a bit overwhelmed on a project. Will get to this during December.

[brunolnetto]

Sure, take your time. The current doc state is ok. IMH, an empathetic documentation however allows any seniority level to use your boilerplate.