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

Subject: Re: [boost] [doc] Liven up Boost Documentation with Java Script?
From: Krzysztof Jusiak (krzysztof_at_[hidden])
Date: 2016-02-26 06:58:30

On Thu, Feb 25, 2016 at 3:18 PM, Krzysztof Jusiak <krzysztof_at_[hidden]>
wrote:

> On Thu, Feb 25, 2016 at 11:38 AM, Rob Stewart <rob.stewart_at_[hidden]>
> wrote:
>
>> 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!
>>
>
> Yea, that was my point for the user to be able to easily experiment before
> really trying the library. A lot of users won't download the library and
> check it out, but IMHO, some of them
> may actually click the button and check what will happen. Moreover, some
> users (me, for example) when see code example are curious what will happen
> if...
> Documentation will not cover all cases, but if user can quickly check it
> might be beneficial, I think.
> If it comes to interaction itself, I was thinking of creating an
> interactive tutorial for the users. For example, a lot of people do not see
> benefits in dependency injection and having
> a quick exercise to adopt code with or without DI could have changed their
> mind.
>
> One of the examples where user can interact a bit more...
> http://boost-experimental.github.io/di/extensions/index.html#types-dumper
>
>
Another example of having online compilation handy is to show code
performance.
For example, with Boost.DI I claim that simple value bindings will generate
following ASM-x86-64:
// ASM x86-64 (same as `return 42`)
mov $0x2a,%eax
retq

However, user can be curious what will happen if I do something else (like
in https://gcc.godbolt.org/), with online compiler you can do that too for
your library.
Example here ->
http://boost-experimental.github.io/di/overview/index.html#performance

Sorry for replaying to myself, I was just thinking it might be useful
sharing that.

>> > * 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.
>>
>
> Point taken. Therefore, I have prepared 3 themes for the users.
> * Boost-Experimental - the fancy one -
> http://boost-experimental.github.io/di
> * Boost-Modern - more like Boost but still interactive -
> http://boost-experimental.github.io/di/boost-modern/
> * Boost - classic Boost (no Java Script) -
> http://boost-experimental.github.io/di/boost/
>
> Boost themes are based on Paul's great work. They are not perfect yet,
> but, I guess, they show the point.
> User can even change the theme with a button provided on the top right
> corner.
>
>
>> > * 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.
>>
>
> Fair point, therefore, on mobile you may want to change the theme to
> http://boost-experimental.github.io/di/boost/
> I actually find out that chats seems to be more useful than comments as
> people are more willing to use them.
> Hana's chat it's quite active and useful.
> * https://gitter.im/boostorg/hana
> * https://gitter.im/boost-experimental/di
>
>
>> > 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.
>>
>
> I agree, that for mobile it might be a bit to much and, therefore the
> http://boost-experimental.github.io/di/boost/ theme.
> I may also add detection in order to choose the most suitable theme for
> the user. Depending on JS enabled/disabled screen size, etc.
>
> Thanks for you feedback.
>
> ___
>> Rob
>>
>> (Sent from my portable computation engine)
>>
>> _______________________________________________
>> Unsubscribe & other changes:
>> http://lists.boost.org/mailman/listinfo.cgi/boost
>>
>
>