Prev: Array not updated in procedure in protected type
Next: More of less most standard Ada binding to POSIX
From: Hibou57 (Yannick Duchêne) on 24 Jan 2010 14:20
To get a quick example, I used to noticed many times, although it is
supposed to targets a wide audience and should be understandable by
principle, open source softwares are just open-source and not open-
documentation.

If there is an area (beside some others) where documentation should
come as a first requirement, this is the area of the open source.

But as much as I've seen so far, it always (nearly, there are a few
exceptions) lacks this.

I'm unfortunately not working for any company, so I've never seen
others except mine and what's publicly available on the web (and
sometime books, but books are a special case which should be discussed
apart).

It would be nice to discuss this topic in the Ada world firstly, and
secondly to have an idea of the state of this art of software
documentation in the none-public area, for those who can't have a
sight in it.

I was driven to open this topic, because I'm right now currently
reading an article about it :
http://www.artima.com/forums/flat.jsp?forum=106&thread=12199

It is named “ The Myth of External Program Documentation ”

Just some excerpt to give you a reason to take some time to read it :

(quotations from the above link)
> "Had the documentation been helpful?", I asked. "Are you kidding?!",
> my friend replied. "It scared the hell out of 'em." I looked aghast.
> He continued, "they take one look at the size of the notebook you
> left and they say I'm not touching that! It looks complicated!"

> While we're on it, how do you explain the reaction to the project
> documentation I'd left for the Prescriber? Is this common? The
> answer to that appears to be "yes"

> Given this large number one might expect that we'd be looking
> for ways to manage this cost and mitigate any associated risks.
> Steve Rakitin, in his book Software Verification and Validation for
> Practitioners and Managers, make the observation (also quoting
> from DeMarco and Lister) that "Turnover is incredibly expensive."

> If you read Computer Science text books you might imagine external
> program documentation such as high-level designs, specifications,
> and theory of operation descriptions actually exist in most projects.
> Yet, when I asked many of my friends and colleagues if they had ever
> had such documentation throughout a project's life cycle, they laughed
> a bit uncomfortably and said, "well, no, not really." What's going on
> here?

Stories and testimonies welcome ;) (as far as this can be done without
violating any running local privacy clauses)
From: Hibou57 (Yannick Duchêne) on 27 Jan 2010 23:56
By the way, GNAT comes with a good example of such a suggested
documentation.
The author of the latter article would probably enjoy to see more
oftenly this kind of literature :
http://www2.adacore.com/gap-static/GNAT_Book/html/

A document which clearly explains implementations strategies and
concepts, with both links to formal specification topics (sections in
the ARM) and parts of implementation which handles these.


P.S. That's also true that GNAT had been largely funded, and that may
have helped (the author alleged that economic considerations may have
to be taken into account).
 | 
Pages: 1
Prev: Array not updated in procedure in protected type
Next: More of less most standard Ada binding to POSIX