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