Boost logo

Boost :

Subject: Re: [boost] Asciidoc, an alternative for documentation
From: Robert Ramey (ramey_at_[hidden])
Date: 2017-10-08 02:12:20


On 10/7/17 10:25 AM, John Maddock via Boost wrote:

>
> Indeed, but there's another issue here I would like to raise:
>
> * How do you know when a library is well designed?
>
> The answer for me at least in part is:
>
> * Can I, starting with a blank sheet of paper, easily explain what this
> does?
>
> I've lost track of the number of times I've redesigned something because
> it failed that test.

WOW - Great minds think alike! I'm hoping you can find time to skip
through the video of my presentation a CPPCon 2017 - if only so you can
honestly endorse it. The short versions is

a) normal process code, test then write documentation. Doesn't work.

b) recommended process: Write documentation in parallel with design and
coding.
step 1: write one sentence description of what the library is meant to do.
Step 2: make a simple illustrative example of how the library is to be
used. If required make more examples.
step 3: make the library to make the examples work.
Step 4: fix library and examples so they make sense.
Step 5: add notes. step 6: Fill in reference documentation using
standard format - e.g. SGI format.

c) This what I do and I think its extremely helpful. The main benefit
is that I find design mistakes sooner so I have to do less rework.
Second benefit is that final product is better and has list "added in"
quirky features.

> The problem I see then, is that tools that extract documentation direct
> from code have the effect of disengaging the authors brain from the task
> of explaining what their code actually does.  Well it does for me anyway ;)

100% agree. I do agree that these tools might be helpful - but only up
to a point.

>
> I've also come to the conclusion that standardese does not make good
> documentation - despite having authored more than my fair share.

LOL - at least you've atoned for your sins. But really the standards
have a different problem. Not so much as to help users, but more
intended to help implementors. I would argue it's whole different problem.

> And now I'll get back to lurking again.... John.

Right. What do we have to do to get you to make a conference appearance
- if only to prove that you're an actual person rather than some robot,
high school student, prison inmate with a life sentence or some thing else.

Robert Ramey


Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk