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

[Martin Baker]

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
> http://web.archive.org/web/20130729214526id_/http://itc.conversationsnetwork.org/shows/detail169.html
> http://web.archive.org/web/20130729210039id_/http://itc.conversationsnetwork.org/shows/detail662.html

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.

Martin