📝💬 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.