Feedback on documentation

[oTree-org]

I am upgrading an old project to channels to 2.x. I found the channels 0.x/1.x documentation very well written and easy to grasp. In contrast, I am having a harder time diving into the 2.x documentation.

First, the intro sections are repetitive. It's a lot of extra text to navigate. For example, these excerpts are all taken from the home page & introduction page:

Channels changes Django to weave asynchronous code underneath and through Django’s synchronous core

It does this while preserving Django’s synchronous and easy-to-use nature, allowing you to choose how you write your code - synchronous in a style like Django views, fully asynchronous, or a mixture of both.

Our belief is that you want the ability to use safe, synchronous techniques like Django views for most code, but have the option to drop down to a more direct, asynchronous interface for complex tasks.

It does this by taking the core of Django and layering a fully asynchronous layer underneath, running Django itself in a synchronous mode but handling connections and sockets asynchronously, and giving you the choice to write in either style.

More examples of repetition:

Channels is a project that takes Django and extends its abilities beyond HTTP - to handle WebSockets, chat protocols, IoT protocols, and more.

Channels allows you to use WebSockets and other non-HTTP protocols in your Django site. For example you might want to use WebSockets to allow a page on your site to immediately receive updates from your Django server without using HTTP long-polling or other expensive techniques.

allowing Django projects to handle not only HTTP, but protocols that require long-running connections too - WebSockets, MQTT, chatbots, amateur radio, and more.

making it easier than ever to extend your HTTP-only project to other protocols.

We treat HTTP and the existing Django views as parts of a bigger whole. Traditional Django views are still there with Channels and still useable - we wrap them up in an ASGI application called channels.http.AsgiHandler - but you can now also write custom HTTP long-polling handling, or WebSocket receivers, and have that code sit alongside your existing code.

I also feel the documentation puts too much up-front emphasis on the flexibility of the system, or talking about how it was built, and in doing so, misses an opportunity to start people off with the basics. For example, the "turtles all the way down" section: https://channels.readthedocs.io/en/latest/introduction.html#turtles-all-the-way-down. This is the second section in the intro, so at this point I don't know what the "turtles" are. It's too early to have an "aha" moment.

Another example, the top of the "Routing" page.

While consumers are valid ASGI applications, you don’t want to just write one and have that be the only thing you can give to protocol servers like Daphne. Channels provides routing classes that allow you to combine and stack your consumers (and any other valid ASGI application) to dispatch based on what the connection is. Routers are themselves valid ASGI applications, and it’s possible to nest them.

I think for newcomers this paragraph is too complex and keyword-heavy, especially since it's talking about something you don't want to do ;) I think the Channels 1.x version was much easier to understand: https://channels.readthedocs.io/en/1.x/routing.html. And the next sentences:

We suggest that you have a ProtocolTypeRouter as the root application of your project - the one that you pass to protocol servers - and nest other, more protocol-specific routing underneath there. Channels expects you to be able to define a single root application, and provide the path to it as the ASGI_APPLICATION setting (think of this as being analagous to the ROOT_URLCONF setting in Django). There’s no fixed rule as to where you need to put the routing and the root application, but we recommend putting them in a project-level file called routing.py, next to urls.py. You can read more about deploying Channels projects and settings in Deploying. Here’s an example of what that routing.py might look like:

I think that can be safely boiled down to this (the rest of the content is already stated elsewhere on the page):

The ASGI_APPLICATION setting is analogous to the ROOT_URLCONF setting in Django. It should be the path to your root application, which we recommend saving in a file called routing.py, next to your project's urls.py. Here is an example routing.py:

[oTree-org]

I also think the introductory section from Consumers (https://channels.readthedocs.io/en/latest/topics/consumers.html) could be reduced:

While Channels is built around a basic low-level spec called ASGI, it’s more designed for interoperability than for writing complex applications in.

what is "it"? Channels or ASGI?

So, Channels provides you with Consumers, a rich abstraction that allows you to make ASGI applications easily.

I think this can be safely deleted.

Consumers do a couple of things in particular:

• Structures your code as a series of functions to be called whenever an event happens, rather than making you write an event loop.

I think this is obvious and can be deleted.

• Allow you to write synchronous or async code and deals with handoffs and threading for you.

Is this necessary to say? The next section immediately introduces AsyncConsumer and SyncConsumer.

Of course, you are free to ignore consumers and use the other parts of Channels - like routing, session handling and authentication - with any ASGI app, but they’re generally the best way to write your application code.

This seems like something most people won't do, so I think that sentence is not necessary in the intro.

[carltongibson]

Hi @oTree-org. Thanks for the feedback. I guess the best way forward is individual PRs suggesting changes. I'll leave this open for now to have a read over a few times but it's a bit too big as it stands (if that makes sense).