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

On Thu, Feb 25, 2016 at 3:18 PM, Krzysztof Jusiak wrote:

On Thu, Feb 25, 2016 at 11:38 AM, Rob Stewart wrote:

...

On February 24, 2016 9:50:13 AM EST, Krzysztof Jusiak < krzysztof@jusiak.net> 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