Re: [boost] Boost documentation

From: David Abrahams (dave_at_[hidden])
Date: 2007-06-24 15:35:10

on Sat Jun 23 2007, "Gennadiy Rozental" <gennadiy.rozental-AT-thomson.com> wrote:

> Hi,
>
> I've been offline for a bit. But I was able to spend several weeks learning 
> DocBook. I must say I was really impressed with quality of this project. I 
> also tried to get a grasp of BoostBook and gave perfunctory look on 
> quickbook. Here I would like to share my thoughts on recent "doc update" 
> movement.
>
> I. quickbook as documentation media.
>
>   Why, oh, why don't we learn from our own mistakes. We just started to 
> realize the problem we got ourselves into with makesystem. And immediately 
> find new toy to play with. However fun it is, however cool it might look on 
> first sight, THIS IS NOT OUR BUSENESS to invent/support documentation 
> format.

That's a concern for me, I must admit.

>  DocBook is very mature, well supported project. It's based on widely 
> accepted/supported technologies. It's powerful and configurable to implement 
> essentially anything one need. I personally don't see much valid reasons to 
> look in home grown format direction. Here some specific points:
>
> 1. Simplicity
>        Some people argues that it's easier to type quickbook 

It is.  And it's easier to read, too, which is even more important.

> I might argue that it's actually opposite. 

Really?

> Granted if you use vi XML editing is not fun.  

Nor XML reading!

> But myriads of modern XML editors simplify the process marginally.

A marginal simplification is hardly enough to make it palatable.

> There several WYSWYG editors producing DocBook (and I don't need to
> enter markup at all!) and this trend is going to grow.

Yeah, but we need to represent semantic information (e.g. Concepts)
that are outside the builtin representational abilities of DocBook.
How well will these WYSIWYG editors handle BoostBook's special tags?

Which editors are these, BTW?

> In addition you get immediate format validation and presentation
> (using assigned stylesheets)
>
> 2. Any change in DocBook have to be reflected in quickbook terms

Problem, but minor.  They're not going to fundamentally break backward
compatibility.

> 3. Someone need to maintain quickbook parser/transformer

Problem.

> 4. quickbook will never be as flexible as DocBook

Disagree.  It's far more flexible, because it has a whole macro
language builtin.  

> 5. This is new *nonstandard* format any new developer will have to
> learn. I don't believe we can afford yet another barrier for new
> submitters.

Unless they already know DocBook, DocBook represents a much higher
barrier for most people getting started.

> 6. Source code highlighting
>
>       My understanding is that quickbook presents some source code 
> highlighting automation. IMO this can be either implemented as standalone 
> C++ based tool that docs writers can use when required or even better it can 
> be implemented in JavaScript. I believe I've seen it done.

I'm not sure I want to do that job on the browser, but I understand
the appeal, especially if end-users can tune the colors.

>  All in all I believe using this format is going to be a maintenance
> problem in a long term and should be avoided. We should stick with
> industry standard DocBook IMO instead.

I don't think it's necessarily that clear-cut.  However, there *are*
other broadly-accepted tools, supported by others, (e.g. docutils)
that we can use to produce DocBook, so it doesn't necessarily mean
we're stuck with XML as our input format if we don't want to have to
support our own front-end.

> II. BoostBook
>
> 1. Complexity
>    The BoostBook being an extension to DocBook seems to be doing too much. 
> IMO any useful generic innovations should be proposed to the DocBook 
> developers and eventually removed. All in all we should strive to make this 
> layer as thin as possible.

I *seriously* doubt DocBook is going to accept C++-specific tags such
as we use for concept documentation.

> 2. Test suites support.
>   I did not really grasp the idea behind this feature completely, but from 
> what I understand this is "misfeature" and should be removed

Well, before you jump the gun you should Google up "literate
programming."  Having an integrated way of testing code examples is
critical to getting them right.  We did that with Boost.Parameter
(using a different system than QuickBook) and it made a huge
difference.  We also used that to test the examples in C++ Template
Metaprogramming.

> 3. Tight coupling with Boost.Build

Huh?

> This is major problem I believe. Especially in documentation. BoostBook 
> should be presented as independent project. It should be explained how to 
> use it, configure it without any reference to Boost.Build at all. At the 
> very last chapter of documentation we may refer that if you want you docs to 
> be automatically generated on some remote host (if let's say you don't have 
> all the tools set up locally for all the formats) this is what you need to 
> do .....

That's a documentation issue, not an intrinsic one.  BoostBook is not
coupled with Boost.Build at all.

> 4. Documentation
> I found documentation to be largely unacceptable (funny thing for the 
> project dedicated to writing documentation)
>
>   a) No explanation how to use BoostBook without Boost.Build (see above)
>
That's a problem.

>    b) all he elements description are without examples
>
That's a problem.

>     c) most critical: no description whatsoever of all the modification done 
> in comparison with DocBook. All the updated parameter need to be listed, all 
> the updated templates need to be explained. General approach should be what 
> the person familiar with DocBook (standard) need to know/expect to use 
> BoostBook

That's a problem.

>     d) No explanation on how to extend the BoostBook (especially in 
> comparison with DocBook)

That's a problem.

> As I mentioned before we should try to limit our extensions to the most 
> necessary only and strive to stick with standard DocBook. Also all 
> extensions should be made optional.

Aren't they, currently?

> III. What should we do?
>
> IMO the standardization efforts need to target DocBook/BoostBook. On the 
> other hand each developer should be allowed to extend/twick standard L&F. 
> Usually differences should be only cosmetic. 

Major cosmetic differences will keep Boost looking fractured.
 
> Following are general 
> observations about common L&F
>
> 1. JS Menu support.
>    I believe it should be implemented but made optional. 

Why not just let the user show/hide it?

> I personally don't like it (I believe it's just wait of space for
> this menu to stay on all the time) and prefer "location path" kinda
> navigation Boost.Test currently using.

Breadcrumbs are nice. 

>  2. Header on top.
>    I don't believe it's necessary. Neither in a form of 
> boost|libraries|more|... nor  what is currently proposed. This information 
> is accessible from boost main page. No need to duplicate it on every page of 
> every library.
>
>   3. Frames
>   I personally need  frames support for the reference like pages (like in 
> preprocessor and test libraries). I am open to the alternative that presents 
> similar L&F.

Frames don't interact well with bookmarks and sending people links
into the documentation.

>   4. Portability
>   This is major requirement for all the features we implement. They should 
> work on at least set of predefined "major" browsers.

Yep.

-- 
Dave Abrahams
Boost Consulting
http://www.boost-consulting.com
The Astoria Seminar ==> http://www.astoriaseminar.com