Feedback on documentation

[Laurent Caillette]

Here are some ideas and remarks after reading the documentation draft

http://projectreactor.io/docs/reference

Hope this helps.

c.

Suggested introduction plan

I suggest to keep introduction's main chapter shallow, then dig every topic in subchapters. If you dig too deep at the start you get the reader totally lost. The solution is to accept to start with some approximations.

• Introduction
  

Reactor is based on Reactive Streams concept, and adds a lot of tooling above. Reactive Streams are a way to program that maximize hardware utilization with non-blocking threads. It has also has a positive impact on code legibility. 

• Reactive Streams
• Copy official definition with "non-blocking backpressure" in italics.
• Why non-blocking is important  [reuse my stuff here, it's easy to get confused with non-blocking IO]
• A bit of history (big names welcome)
• Base contract (the 4 interfaces, figure 3)
• Example of blocking code [I love this part but it's a bit long to start with]
• Reactor framework: layers and dependencies
• Reactor framework: project history

Suggested introduction for reactor-core

Reactor-core offers a layer of logic to tie components with Publish-Subscribe relationship, in a manner that respects the Reactive Streams contract. The two most important notions are Processors, and Dispatchers.
A simplistic (but useful) approach is to see the Processors as boxes encapsulating the logic, while the Dispatchers chose the right threads to run them.

Suggested introduction for reactor-streams

Reactor-streams refine the Publish-Subscribe contract by establishing chains of Processors with well-known patterns like filtering or fork-join. 

About diagrams

I found those readable and useful:

• Figure 1. The main modules present in Reactor 2.0
  
• Figure 3. The Reactive Streams Contract
  
• Figure 4. The Reactive Streams publishing protocol
  
• Figure 6. RingBufferDispatcher at a given time T (cube colors need legend)
  
• Figure 7. RingBufferProcessor at a given time T, with 2 Subscribers
  

Other diagrams are overcrowded. The Doge de-dramatizes them but doesn't make them more readable. 

I write a lot of technical documentation and I found those approaches helped me to create readable diagrams:

• Forbid Visio and all that sophisticated stuff.
  
• Use A4 sheet of paper with a big marker pen, too big to write many boxes or letters. Pro: rework is cheap. Drawbacks: need to scan the drawing; updates are a pain.
  
• ASCIIart with a maximum of 100 columns. ASCIIart is pretty hard do make look good so you really //think// about what you want to draw.
  

Huge diagrams are mainly useful for who is writing them. 

I've never tried this but I like the idea:

http://asciidoctor.org/docs/asciidoctor-diagram

Document layout

I love Netty's dynamic navigation bar (on the right). It really helps and the longer the documentation get, the more useful I find it.

http://netty.io/wiki/user-guide-for-5.x.html

The left navigation bar in Reactor's documentation sometimes refuses to scroll (at least with Safari 7.1.6). That's pretty annoying.

[Stephane Maldini]

Very much awesome advices so far, I like ASCII diagrams too actually. I do reckon the Doge charts are making a fool attempt to make the pill at least funnier to swallow. I'm pushing updates around Stream for now and try to close that part before I revisit the core again with your feedback.

 The core and the overviews are a bit extensive to make sure we do proper education on why there is all this stuff. I've got a few feedbacks in the past year of dev from people still wondering why and where you should be non blocking, why we need an API to coordinate tasks or even why backpressure matters (because after all we can use unbounded queues for everything...).

About the ToC, I have a friend designer willing to contribute something for this and the site globally, I used to know how to quickly tune this kind of things but I flushed that brain cache to replace with some other entries :(

--
You received this message because you are subscribed to the Google Groups "reactor-framework" group.
To unsubscribe from this group and stop receiving emails from it, send an email to reactor-framew...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--

Stephane Maldini | Solutions Architect, CSO EMEA | London | Pivotal

W: pivotal.io | T: @smaldini