Re: [boost] Asciidoc, an alternative for documentation

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