[W3C docs] We should teach by example.

I have been looking through the source code of the "HTML 5 differences
from HTML 4" document [1] as part of the Spanish translation task
along with Alejandro Fernández and it came to my notice that the
source is in pretty bad condition.

Documents are coming from the W3C should not just comply with
standards, they should teach by example on *how* documents are to be
written.

One of our greatest concerns as a web standards group is
accessibility, so why not format the code in a friendly human-readable
manner?
I have a deep respect to the mantainer of the document, but i'm
greatly concerned on what the people see when they peek at what should
be exemplary source code.

The Spanish document is not yet complete as we are still dwelving with
some wording issues, but i'm formatting the source in a more
human-readable form so once it is complete you can pick up that
formatting or we can just discuss together on how we should write
technical documentation.

[1] http://www.w3.org/html/wg/html5/diff/


regards,
Gonzalo Rubio (gonchuki)

Received on Friday, 6 July 2007 05:11:30 UTC