Waldek Hebisch wrote: > I think we have conflicting paradigms here. I belive that history > has place in documentation only if it explains _significant_ aspect > of current system. In case of current filename change past status > really tells you nothing about new system.
(insert 'mouth 'foot) At the risk of getting into trouble, I must agree with Waldek that there needs to be a distinction between documentation of the system which describes its workings, and documentation which describes its evolution. (If that is a fair characterization.) Changelogs are, AFAICS, what we make them. If we are planning to remove or restructure something and want to explain why we are shifting from the old to the new, that seems to me like a Changelog type of entry. If normal changelogs are too brief for what we are after and don't highlight exact changes, why not create a changelog format that does what we want? I have always thought that if we are making Axiom into literate documents, they should read as such - if I am looking for the pamphlet that describes the SPAD compiler I am interested in what it IS doing and what it is intended to do and why, not what it did in the past before it was fixed. If I run into a bug I might want to check what changes were made and why, but that is the precise purpose of a changelog - to preserve the description of system evolution. If we want more extensive changelogs than are standard today, let's define what would work for us. However, I must agree that I wouldn't want such things cluttering up the pamphlet. If the job that (say, for example) PDP11 specific code did has no modern equivalent and is no longer needed, removal and a changelog entry should suffice. We don't need to document why that code was there and how it worked if it handles a problem that no longer exists. That's why I took the approach I did with the Units paper - study the problem domain, determine what should happen, and then make the code fit the ideas. When I tried a Maxima units package I did it the other way around, and while the code does do some things I rather doubt it would scale correctly or handle some of the more subtle questions/issues. Admittedly there isn't working code for Axiom yet, but the eventual result of the Unit paper approach will be much more useful. To take another example, I would like to see us first write the paper/book on WHAT the SPAD language definition is, WHY we want it that way, and HOW we want it to work (compilation algorithms, compiler design considerations, etc.). In the process, we will probably learn how it SHOULD be done, rather than how it is done now. The existing code will be very useful as a reference and some pieces might be drop in, but I would like to see the ideas lead the code instead of the code leading the ideas. In such a paradigm, what the old code was doing is less important than the question of do we have code that does the right thing? The pamphlet literature then is driven not by the existing code but by what the code SHOULD be, and in that sense adding notes for the reasons for removal of old code are beside the point of the document. Such removals should indeed be explained, but in the changelogs and not the document itself. If the changelog should reference specific files/line numbers as part of its format that makes sense to me - perhaps there is a way to automate that as part of the SCMs. Anyway, my 2c. Cheers, CY _______________________________________________ Axiom-developer mailing list Axiom-developer@nongnu.org http://lists.nongnu.org/mailman/listinfo/axiom-developer
