[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Axiom-developer] Must hear...

From: Martin Baker
Subject: Re: [Axiom-developer] Must hear...
Date: Sun, 11 May 2014 09:56:50 +0100
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:24.0) Gecko/20100101 Thunderbird/24.4.0

On 09/05/14 18:16, Tim Daly wrote:
With respect to "documentation" of open source software...

"You keep using that word. I don't think it means what you think it
means." -- "The Princess Bride"

The notion that "reading the code" is the ultimate truth for
"documentation" is based on a misunderstanding at so many levels it is
hard to explain. In fact, most of the ideas don't begin to cover
"documenting the system". Fortunately, Robert Lefkowitz absolutely
illuminates the scope of the problem in these delightful talks.

For those who have not heard it, this is truly a treat.
For those who "document" this is a must-hear.

Robert Lefkowitz -- The Semasiology of Open Source

So what should one do if one wants to modify parts of Axiom (or its forks) where all there is is the code?

Should one:
1) Trace through the code and try to reverse engineer the documentation, then modify that. 2) Try to understand generally what it does (such as working out what the inputs and outputs are). Then rewrite it from scratch in a documentation led way.

For me, in a lot of cases, I would prefer option 2. I would not claim to be as smart as the original authors, any algorithm that I would come up with might be less efficient and inferior in many respects. However I would try to document it as well as I could and try to make it a better basis for future improvement. Also, if I am going to make mistakes, at least I would learn more from my own mistakes.


reply via email to

[Prev in Thread] Current Thread [Next in Thread]