[Issue 677] [Tracker] Get the documentation cleaned up for 1.0

[d-bugmail at puremagic.com]

http://d.puremagic.com/issues/show_bug.cgi?id=677





------- Comment #4 from smjg at iname.com  2007-02-09 14:31 -------
Moreover, if you're going to include a diff, then including one that's as big
as the code file or bigger is practically useless.  There are two reasons for
having diffs:
(a) to save disk space/bandwidth by storing/transmitting only the changes to a
document rather than the whole updated document
(b) to draw the human reader's attention to which bits have actually changed

By changing the indentation style as well as fixing up the content, you have
created a diff file that's bigger than either version of the code.  What's
more, we have a hard time finding the bits where you've actually changed the
content among the mass of indentation fixes.  Hence both benefits are lost.

On this basis, it would have made more sense to upload just your updated
version of the page.  You could, however, have gained benefit (b) by fixing the
indentation first and then diffing between this intermediate version and that
with your content fixes put in.


--