On 10/19/2017 11:49 AM, Robert Ramey via Boost wrote:
On 10/19/17 8:40 AM, Hans Dembinski via Boost wrote:
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 don't think there's a conflict. Quickbook is just a way of producing boostbook. I'm thinking that you can just include code file from quickbook just as you can from another boostbook editor. I don't know this for a fact though. My real point is that you can let the documentation depend on your coded examples so that they are always in sync and that it is generally very easy to do.
I believe that writing good documentation is not solvable by a tool, +1 although it certainly helps if the tool is easy to use and not in the way. +1 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.
I see the appeal of Quickbook and other markdowns. But all such attempts suffer from all attempts to make a "new" language. It's much more work than it first appears. So if it's helpful, the demands for maintenance and extension eventually overwhelm the original design, which then generates the next attempt. It's a never ending quest.
XML may be decent as a way of creating and passing around data in a structured way, but having to write documentation in XML is a hopeless task AFAICS. Quickbook is hugely superior and is a no-brainer to use. If others prefer Asciidoc that's fine also. The point is that nobody need write docs in XML if they do not want to and I do not think that most people want to. I certainly don't.
For me the conclusion is this: the recipe for good documentation is just like the recipe for good code. It requires reviews and iteration.+1
Best regards, Hans