Restructure documentation

[HomerusJa]

Summary

Briefly describe the feature being introduced.

Changes

Create a more elaborate documentation structure to reflect all the different topics suggested. This is a work in progress and I will work on incrementally filling all the pages. This will be a process (-:

Checklist

I deleted the old checklist as it didn't fit to this special PR. Instead, I will use this section to create a checklist of which pages have been written:

Here's a checklist of pages for your PR:

Introduction

• [x] Overview (index.md)
• [x] Getting Started (getting_started.md)
• [ ] Changelog (CHANGELOG.md)

HTTP Backends:

• [ ] Overview (backends/overview.md)
• [ ] AIOHTTP Integration (backends/aiohttp.md)
• [ ] HTTPX Integration (backends/httpx.md)
• [ ] Requests Integration (backends/requests.md)
• [ ] Switching Backends (backends/switching.md)

Advanced Usage:

• [ ] Overview (advanced/overview.md)
• [ ] Authentication (advanced/auth.md)
• [ ] Query Parameters (advanced/query_params.md)
• [ ] JSON Serialization (advanced/serialization.md)
• [ ] Error Handling (advanced/errors.md)

Performance Features:

• [ ] Caching: advanced/caching.md
• [ ] Rate Limiting: advanced/rate_limiting.md
• [ ] Retries: advanced/retries.md

Examples:

Here, work needs to be done specifying which examples should be used.

Internals:

• [ ] Architecture Overview (internals/architecture.md)
• [ ] Endpoint Descriptor (internals/endpoint_descriptor.md)
• [ ] Request Lifecycle (internals/request_lifecycle.md)

Contributing:

• [x] Contributing Guide
• [x] Code of Conduct
• [x] Security Policy

API Reference

This currently works, but is pretty unstructured. Maybe work on this later.

Additional Notes

Any additional information or context relevant to this PR.

[HomerusJa]

@pmateusz Is there a reason why ci.yaml and check-branch.yaml are two distinct workflows, as ci.yaml just calls check-branch.yaml? If not, I will change that.

[pmateusz]

@pmateusz Is there a reason why ci.yaml and check-branch.yaml are two distinct workflows, as ci.yaml just calls check-branch.yaml? If not, I will change that.

The only difference is the concurrency limit ci.yaml includes, so there can be only one instance of a GitHub action job that checks the master branch. On the other hand, there is no restriction on the number of jobs checking pull requests.

The concurrency limit is not that important anymore because the release is taken care of by a different GitHub action. Feel free to remove the ci.yaml after moving the push trigger definition to the check-branch.yaml.

[HomerusJa]

Also, the changelog has not been kept for ages. Do you still want to include it? If so, do you want to get it up to date or just start from this point onwards? Also, would you consider using some automatic changelog generation tool, or would you mind to ad adding a changelog entry to the PR template checklist?

[HomerusJa]

Finally, do you have any specific suggestions/ideas/wishes for the documentation? Do you have an idea of how to release this documentation before every single category is finished? What about adding a label on the introduction page stating that the documentation is a work in progress and linking to an issue tracking the progress?

[pmateusz]

Also, the changelog has not been kept for ages. Do you still want to include it? If so, do you want to get it up to date or just start from this point onwards? Also, would you consider using some automatic changelog generation tool, or would you mind to ad adding a changelog entry to the PR template checklist?

Let's remove the changelog. I used GitHub to generate release notes based on changes made since last release. Personally, this I find this sufficient. I would like to keep things simple and don't overload people with processes.

[pmateusz]

Finally, do you have any specific suggestions/ideas/wishes for the documentation? Do you have an idea of how to release this documentation before every single category is finished? What about adding a label on the introduction page stating that the documentation is a work in progress and linking to an issue tracking the progress?

Overall it was interesting to me to see how you would structure the documentation. Your proposal makes sense to me and is justifiable. I would not discuss minor changes here such as changing the title of a section. I believe it will be faster to apply them after your changes are merged.

Regarding writing style, I would suggest the following:

• try to reduce redundant words, so the text can be read quickly
• avoid passive voice whenever possible
• prefer short sentences Grammarly is great for reinforcing these habits and gives instant feedback.

I would skip the section internals or would do it last after all other sections are completed. I believe it is outside the interest of a general user. If somebody is interested they would clone the project and figure it out themselves.

The way I would partially publish documentation depends on how long would it take to publish missing pages.

1. We could create ./docs/v2 directory and keep the new documentation there. Once the documentation is ready for publication, we will replace the existing documentation with the new version,

2. Otherwise, we could create a new file structure and mark the remaining files as work in progress.

Either way is OK for me.

[eidorb]

Thank you for the existing documentation.

Here's an excellent resource for structuring documentation: https://docs.divio.com/documentation-system/. Watch the video for a quick intro.

I think the cookbook falls under how-to guides. A useful addition would be something like how to progressively reverse engineer an API. That would show how you start with simple stubber methods for endpoints returning generic dicts. Then as you type out parameters and responses as you document the API. It's a fun process. I have some notes. Perhaps it would be better as a tutorial...

[HomerusJa]

That's a great source. I will look into how it affects the current plan later.

Also, thanks for your suggestion!

[pmateusz]

Thank you for the existing documentation.

Here's an excellent resource for structuring documentation: https://docs.divio.com/documentation-system/. Watch the video for a quick intro.

I think the cookbook falls under how-to guides. A useful addition would be something like how to progressively reverse engineer an API. That would show how you start with simple stubber methods for endpoints returning generic dicts. Then as you type out parameters and responses as you document the API. It's a fun process. I have some notes. Perhaps it would be better as a tutorial...

@eidorb, thank you for sharing the video! I realized nobody told me before how to structure and write documentation. I learned it by observation and following other projects, but I missed the structure the speaker explained in the video. It looks I underestimated the importance of a tutorial :bow:

[pmateusz]

@HomerusJa, I saw you seem to have stopped working on this PR. I wanted to make tutorials available as soon as possible, for that reason, I wrote some basic tutorials aimed at novice users to show them on hand how to send basic HTTP requests, implement authentication, caching, and rate limiting.

The style follows guidelines suggested in the video shared by eidorb, i.e., a reader is led step by step and is presented with one solution to accomplish the goal without derailing the topic to more advanced subjects or alternative solutions.

[HomerusJa]

Yea, I have a lot to do currently, so I don’t really have time to work on this project right now. Still, you can happily take everything I‘ve written.

[pmateusz]

Yea, I have a lot to do currently, so I don’t really have time to work on this project right now. Still, you can happily take everything I‘ve written.

Thank you for the prompt response and the effort you put in :bow: