Alain.Cochard@unistra.fr writes:

>  > Will it help if we mention this fact in "16.6 Results of Evaluation"
>  > section?
>
> Yes, it would help me.  At least I would been warned.  But it would be
> complete only if knew where to read about each specific babel backend.
>
>  > > For the sake of newcomers, it seems to me that something along the
>  > > line of what you write above would fit somewhere in 16.6, with a first
>  > > short mention/warning (and reference to it) next to that excerpt in
>  > > 16.5:
>  > >
>  > >    Org captures the results of the code block evaluation and inserts
>  > >    them in the Org file, right after the code block.
>
>  > Talking about ob-shell does not belong to this section of the
>  > manual.  Other backends have different behaviour. Have you seen
>  > examples in
>  > https://orgmode.org/worg/org-contrib/babel/languages/ob-doc-shell.html
>  > ?  Are they not clear enough?
>
> No, I had not seen this before.  If I had, I might have understood why
> I was getting the "strange" output that originated this thread -- but
> I do not find it explained as clearly as you explained it:
>
>    "In the case of two commands returning output, the guess is
>     yielding the table. In the case of a single command, the guess is
>     yielding a single string output."
>
> I can now see that the ob-doc-shell.html page is (indirectly) referred
> to in 16.9, via
> https://orgmode.org/worg/org-contrib/babel/languages/index.html.
> Maybe this is enough for some, but for me it is too convoluted.  I had
> seen this page, but it was a long time ago, when I checked whether the
> languages I use were supported or not.  So why not also refer to it in
> 16.6, together with the mentioned fact to which you are referring
> above?

See the attached patch with tentative changes to the manual.
Let me know if you think that things are still not clear.