Re: [boost] [BoostBook] how to automatically test code examples?

Subject: Re: [boost] [BoostBook] how to automatically test code examples?
From: Hans Dembinski (hans.dembinski_at_[hidden])
Date: 2017-10-19 15:40:33

Dear Robert,

> On 19. Oct 2017, at 16:24, Robert Ramey via Boost <boost_at_[hidden]> wrote:
> 
> I make up my examples in the "example" directory.  This includes a Jamfile to build and run the examples.
> 
> I create the BoostBook xml using and XMLmind - an xml editor.  Within that environment I just use an "Include" directive to include the source code of the example in the correct place - easy as pie.  If you download the slides associated with my recent CPPCon presentation, you can see how it's done.
> 
> https://www.youtube.com/watch?v=YxmdCxX9dMk <https://www.youtube.com/watch?v=YxmdCxX9dMk>
> 
> you can download the slides and example here:
> 
> http://www.rrsd.com <http://www.rrsd.com/>

thank you for these pointers. :) Sorry again, I mixed up BoostBook with Quickbook. Since I already wrote 90 % of the documentation in QuickBook, so I am going to stick to that for now.

I watched your talk on Youtube a few days ago and I think it was a nice talk. I think we need more talks about code documentation.

I believe that writing good documentation is not solvable by a tool, although it certainly helps if the tool is easy to use and not in the way. So far, I liked the Markdown variants best of all markup languages. Since Asciidoc is similar, I am glad that it was discussed on the list recently.

For me the conclusion is this: the recipe for good documentation is just like the recipe for good code. It requires reviews and iteration.

Best regards,
Hans