Proper docs site

[j4mie]

This uses mkdocs and mkdocs-material to set up a proper documentation site, which will be hosted on GitHub Pages.

The structure of the top-level pages is based on https://diataxis.fr/

Still to do:

• [x] Docs on how to build and work on the docs (ie add to README)
• [x] GitHub Action to deploy on pushes to main
• [x] Remove docs branch from the trigger under push in the actions config
• [x] Actually write the docs
• [x] Register a domain (django-readers.org?)
• [ ] Set up github pages to point at the custom domain
• [x] Remove the "work in progress" banner from the homepage
• [x] Eviscerate the current README to remove all the current docs

[simkimsia]

How can I help?

[j4mie]

How can I help?

Thank you for the offer! I want to get a little further with writing this before I get help from contributors, but once it's ready for review then I'll shout.

[j4mie]

@simkimsia 👋🏻 if you still had any time and want to give the docs a quick read, that would be brilliant. You can see a preview at https://dabapps.github.io/django-readers/

[simkimsia]

@j4mie the theme looks nice. I like how the right hand side menu expands and is sticky.

I am familiar with diataxis.fr quadrants.

In the past, I agree with it. Now I am inclined to think in terms of:

1. procedural understanding (this would map to your cookbook or how-to in the diataxis quadrants)
2. conceptual understanding (this would map to your explanation)
3. reference (this is your typical API docs or reference)

Where did I get the terms "procedural understanding" and "conceptual understanding"?

I got them from DigitalOcean style guidelines for writing tutorials. Here are the templates https://github.com/do-community/do-article-templates. Note that DigitalOcean have two kinds of procedural understanding tutorials in software dev and systems procedural.

I personally find DigitalOcean tutorials esp those for systems procedural to be the gold standard as a user.

I also prefer one procedural understanding one page. One conceptual understanding one page. Not squeeze all the tutorials and explanations all in one page.

Of course, this being your repo, you have the final say how to display the contents. I promised to be honest as enduser-developer. You don't have to follow or agree with me.

[j4mie]

I also prefer one procedural understanding one page. One conceptual understanding one page. Not squeeze all the tutorials and explanations all in one page.

Interesting, thanks. I think I'm happy with the structure how it is now but will read through the Digital Ocean stuff.

[simkimsia]

Thanks for asking me. Either way, I'm happy to see the docs gone live now. 🙌

[simkimsia]

Yeah 🙌🙌🙌