|
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