📝💬 Discussion about the documentation improvements #contributeit

[Arfey]

Hello everyone 🤚.

We want to improve the documentation of aiohttp. To do this, we need to know what, in your opinion, is not well-described in the current version of the documentation and how to make it better.

If you have any advice or want to help writing the documentation, feel free to reply to this issue 👇.

[webknjaz]

I think, it's important to ask this question on the other avenues like the mailing list and the Gitter chat.

[asvetlov]

Pinned the issue to make it broader visible

[samuelcolvin]

I entirely agree that documentation could do with improvement.

I have some criticisms/suggestions, but first it's important to say that in general aiohttp's docs are great - these are just suggestions of ways of making it even better.

Markdown vs. reStructuredText

Many developers find markdown much more intuitive to use than rst. I know rst has many powerful features but it's also extraordinarily convoluted to do simple things eg. links are

`name <https://www.example.com/>`_

I find this amazingly complex. Even after having written thousands of lines of it, I still have to google or search for an example of things that are trivial in md.

I think lots of people would be more willing to help with the docs if they were written in markdown. However I know python's own docs are written in rst so many of you will be very hostile to moving to md.

I recently migrated pydantic's docs from sphinx (see here) to mkdocs (see here), it took some time but I think the results are much better.

Tutorial vs. Quickstart vs. Advanced Usage vs. Reference

Let's say I want to find the docs on "middleware". Which section are these in? I've no idea, I have to go to google and search from there. I even wrote some of these docs, so imagine how hard it would be to navigate when you're new to aiohttp.

Sphinx encourages you to split docs into "reference" - auto generated from docstrings and free form documentation with a narrative, however I find this to be a very confusing way of structuring documentation.

I think the docs should have a simple intro, then be split into sections based on logical components rather than "quickstart" vs." advanced usage" vs. "reference".

Perhaps since it would be extremely difficult to rewrite all docstrings in markdown (and I don't know of a popular markdown documentation tool that extracts docstrings), we could keep the reference section somehow generated from docstrings, and link to it in the rest of the docs. See mkdocs/mkdocs#20

Therefore I would propose a documentation structure something like:

• Intro
• Installation - included option extras
• Server:
  • app
    • startup
    • shutdown
  • routing
  • views
    • request
    • response
    • websockets
  • middleware
  • signals
  • logging
  • testing
• Client
  • session
  • requests
  • cookies
  • tracing
  • testing
  • etc.
• Using aiohttp
• contributing

I'm sure I've missed quite a few things, but a structure roughly like this would (for me) be massively easier to use.

English

Entirely understandable, but in quite a few places the aiohttp docs aren't written in the best grammar. I'm dyslexic, so not much better, but I could improve some of this. However the best approach would be to find another native english speaker to improve the english.

---

In short, I would suggest giving serious thought to moving the docs to mkdocs.

[asvetlov]

1. mkdocs is great but I really love sphinx markup (.. function:, :func: etc) and ability to write own plugin if needed. We do it for documenting async stuff.
2. The documentation structure is subject to change, sure. Initially, it was just Usage and Reference sections, for both client and server. After documentation grows I'd split Usage into Quickstart and Advanced 2 years ago. Now the documentation is even bigger, a perfect chance for additional splitting.
3. I think that Reference section is still relevant. We don't use autodoc for aiohttp documentation, everything is hand-written.
   Maybe it is related to my personal style of working with documentation; I usually need both narrative text about the feature usage and a reference, a formal list of public API objects and their methods pushed together.
   This is not the only way to organize docs; Python doesn't use Reference concept but it provides state-of-the-art documentation.
   At least I've found Reference very useful when people make a pull request that modifies Public APP,. Very often it's not obvious where Quickstart/Advanced docs should be updated to reflect a new function argument but at Reference provides a clear way to reflect the change (at least mention it without comprehensive description).
4. Regarding English -- please don't hesitate to prepare PRs with improvements. You know, my English is weak. I would say that my written English grows with aiohttp documentation (issues, PRs, other FOSS projects) mainly ;)

[asvetlov]

The article about documentation writing: https://www.divio.com/blog/documentation/

[samuelcolvin]

The article about documentation writing: https://www.divio.com/blog/documentation/

Ye, I saw that on HN. It describes exactly what I disagree with - having documentation split into multiple different narratives is very annoying for casual users and regular users alike.

I can just about imagine having narrative and reference or tutorial and explanation; but 4 sections!!? That's just a recipe for confused users and out-of-date documentation.

mkdocs is great but I really love sphinx markup

I can see I'm not going to win on md :-), which I can understand. I think the much more important thing is the structure of the documentation.

This is not the only way to organize docs; Python doesn't use Reference concept but it provides state-of-the-art documentation.

I think python does it right.

---

I think multiple sections is just an extra cognitive burden and increases the chance documentation becomes out-of-date because you have to remember to update multiple different places.

However if I can't persuade you to move to one source of truth for a feature, could we reduce it to two maximum?

For example: currently if I want info on how to use websockets, it could be split across:

• Server > Tutorial
• Server > Quickstart
• Server > Advanced Usage
• Server > Reference
• Utilities > WebSocket utilities

Surely that can't be good? For comparison Starlette has one page https://www.starlette.io/websockets/ with all info on websockets.

Regarding English -- please don't hesitate to prepare PRs with improvements

Life is always too busy, but I'll try.

[asvetlov]

I don't know how many parts are good.
I think the problem of any docs reorganization is that hard to say if the new approach is good before looking at the complete new version.

Let's look at click docs: several chapters of domain-oriented topics (parameters, options, commands etc) plus a full reference.
What do you think about this style?
After uick look on starlette I would say I miss cross references befween parts (CPython uses them intensively despite the fact that it has no strict usage-reference separation).

[samuelcolvin]

I agree link between different docs sections is vital. This is one of the things sphinx/rst does better than mkdocs/md.

I agree the click approach is good, though until today I never new there was a reference section - I just read the domain oriented topics and read the code if that didn't suffice.

[asvetlov]

Different style of thinking :)
I usually read the Reference section to figure out what is a part of official public API and what is a leaked implementation detail (even it doesn't start with the underscore prefix).

[tobias-hd]

Being a quite fresh user of aiohttp server and client, I'd like to add some proposals that I ran into, when studying the (already very supportive!) docs:

1. When starting from scratch, "Quickstart" is more important than "Tutorial", I think. Hence the first should be before the latter - specifically, since "Tutorial" actually navigates away from aiohttp's docu pages.
2. The navigation and menu structure took quite some time for me to understand. When starting from scratch with aiohttp server, the main page overview (https://docs.aiohttp.org/en/stable/web.html) was the most important page for me. But I struggled to find it from the main Navigation! - until I realized that the main sections linked in the "Navigation" area (Client, Server, Utilities, ...) are actually not content pages, but only lists of links to subsections. I think this is a somewhat unexpected concept that should be improved.
3. The naming for the main section "Who uses aiohttp" is misleading. I expected here a list of companies/projects that use aiohttp productively. This is actually the content of the subsections "Built with aiohttp" + "Powered by aiohttp" (btw, what is the difference between these two?). However, much more important for me was the subsection "Third-Party libraries", which contains very helpful tools around aiohttp. Until just now, I did not know where actually to find again this page. This subsection should, in my opinion, go into "Utilities", or something similar.

Any thoughts about that?

[webknjaz]

I'd like to augment @samuelcolvin's take on Markdown. I personally like the RST markup but it's understandable that some folks, especially newbies, find it difficult at start.
I know that there's been attempts to integrate Markdown support into Sphinx that had a lot of limitations that thus never became truly popular (recommonmark).
OTOH I've heard that some projects allow contributing new docs in Markdown that may later be converted into RST by more proficient contributors (https://youtu.be/0ROZRNZkPS8?t=502s). I'm leaning towards the opinion that it's a good approach to follow.
But what do we do with the recommonmark limitations? Turns out that at the beginning of 2020 a significant project emerged that allows using RST roles and directives from within Markdown documents. It's called MyST: https://myst-parser.readthedocs.io/. It seems like it's a great tool and it is well-maintained too.
That said, I'd be open to adding this sphinx extension as an extra source parser for *.md files and seeing how it goes.

[webknjaz]

Here's a few more resources on the docs writing topic:

• https://diataxis.fr — how to structure stuff
• https://www.writethedocs.org/slack/ — a place with a lot of tech writers (has channels for diataxis and sphinx among others