Re: [boost] [doc] Liven up Boost Documentation with Java Script?

Subject: Re: [boost] [doc] Liven up Boost Documentation with Java Script?
From: Rob Stewart (rob.stewart_at_[hidden])
Date: 2016-02-25 06:38:02

On February 24, 2016 9:50:13 AM EST, Krzysztof Jusiak <krzysztof_at_[hidden]> wrote:
> Dear Boosters,
> 
> I'm writing to ask about your opinion regarding more interactive
> documentation for Boost.
[snip]
> I would like to know what the Boost community thinks
> about having following
> features in the documentation...
> 
> * Run the code online (allows to check library with one click)

I see no value in that. The library is supposed to be in good working order and I wouldn't care to verify that from the docs. Instead, I'd expect a link to where such things can be viewed and managed.

I just looked at the DI docs and I now see that you meant being able to run sample code shown in the docs. If the sample program was somehow interactive or the code was editable such that one could experiment with it, then I can see the value.

Your "Run this code!" button hides some of the code!

> * Comments (allows commenting on the documentation)

I can understand that comments would permit quick notes on what's lacking or unclear, but I also wouldn't want comment loading to slow page loading or for their display to detract from the information. Thus, having a means to display them, on demand, probably with a sticky bit, would be a reasonable compromise.

> * Chats (allows discussing issues and solutions)

I don't think a documentation page is the place for that, though I have seen some value in such commentary on some MSDN pages. Still, a link to such discussions should suffice.

Your floating chat button is actually rather annoying, especially when viewing the content on a small screen.

> Please, check it out (JS is required)...
> http://boost-experimental.github.io/msm-lite
> http://boost-experimental.github.io/di

Perhaps I'm just too staid, but that page is horribly busy. My screen was filled with large blocks of color and all sorts of distractions. I had to scroll down a good bit before I even saw the word "Introduction". Add the ever-present "Chat" button, the run this, run that buttons, etc. and it's much too busy.
___
Rob

(Sent from my portable computation engine)