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

Subject: Re: [boost] [doc] Liven up Boost Documentation with Java Script?
From: Robert Ramey (ramey_at_[hidden])
Date: 2016-02-24 11:06:39

On 2/24/16 6:50 AM, Krzysztof Jusiak wrote:
> Dear Boosters,
>
> I'm writing to ask about your opinion regarding more interactive
> documentation for Boost.
>
> I know already that some of you would like to see online documentation
> without Java Script and that's absolutely fine and I agree that
> documentation should be available for anyone and any configuration.
>
> Nevertheless, 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)
> * Comments (allows commenting on the documentation)
> * Chats (allows discussing issues and solutions)
>
> Personally, I have found above features extremely useful when checking out
> other languages/libraries and therefore I have implemented solutions for
> C++ too.
>
> Please, check it out (JS is required)...
> http://boost-experimental.github.io/msm-lite
> http://boost-experimental.github.io/di
>

I've also had some experience using this while delving into PHP 
libraries. PHP as a language isn't interesting for us of course. But the 
documentation / documentation/comment I found very useful. I can't see 
chat working out well - but no harm in experimenting with it.

This experience has influenced my decisions regarding the boost library 
incubator which strongly encourages comments and reviews by users on 
submitted libraries. Though the incubator has some modest success in 
some areas, it's been a disappointment in others.

a) The comment facility isn't used much.  One issue is that there are 
lots of other places where one can comment / ask questions about a 
library.  StackOverflow, Boost Developer/Users lists, github issues for 
the library and maybe others.  Comments tend to accumulate around fewer 
hubs.  In retro spect this is not a surprise.  I guess I should tweak 
the inclubator to point to one or another comment area rather than 
implement it's own.  This would be inline with the incubators 
implementation philosophy to avoid doing anything already done.

b) the ability to comment on documentation - posting clarifications, 
questions about the documentation, etc. Is worthy of consideration.

> If there is an interest I can provide generic solution to allow developers
> to write documentation
> using markdown (mkdocs) and simply integrate it with their libraries.
> Currently, theme is just slightly modified version of readthedocs, however
> Paul Fultz II has prepared a boost theme for Fit library (
> https://github.com/pfultz2/mkdocs-boost) already and it might be easily
> integration with the JS facilities provided.

But this is totally the wrong way to go about this.  We have a 
documentation infrastructure which, for the most part, works quite well. 
  I produces relatively high quality linked presentation which is 
consistent accross those boost library (the majority) which use it.

I'm very familiar wiht Paul Fultz TICK library documentation and found 
it to be unworthy of the underlying package.  Most of the problem is the 
text, reference, lack of examples, weak tutorial etc.  But the 
presentation as a web page is quite different that the boost libraries. 
It's jaring and not as effective.  There is also - as far as know anyway 
to produce a PDF version of the documentation.  This last is something 
the Boost Documentation system can do - albiet reserved for those who 
prefer to do their own dentistry.

But it's not at hopeless.

A short time ago, someone present some javascript which would add disqus 
commenting to each page of the documentation.  With the current boost 
book system, it would be quite easy to create an xslt script which could 
be included in the xml -> html transformation pipe which would add the 
javascript commenting to each page the library.  I would guess that this 
would take between 10-50 lines of xslt script code. It would be the 
documentation authors choice as to whether he would want to include this 
or not.

To summarize

a) create the xslt script to add commenting to each page when html 
output of documentation is created.

b) convince authors to try the new script they generate their 
documentation.  They do not have to change one line of their xml 
documentation or it's generation.

c) If they don't like it, they just go back the old script.

d) If your idea "sells", you're done.  If not, you're also done.  In any 
case, you will have achieved everything you desire in only 50 lines of code.

e) caveat - xslt script is the probably the second most annoying 
scripting language I've ever had to deal with.  Sure, it's only 50 
lines, but it probably takes a few days learn about the whole XML tool 
chain to get it right.

Good Luck with this.

Robert Ramey