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-25 10:18:06

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

> > * 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
>