- fix up remaining conversion issues (mainly in “prose” sections)
- reorganize the overview sections (syntax, data model, execution model, etc)
- merge syntax and semantics material, where appropriate.
- add more cross-references/see-also stuff:
- add reference pages for core types
- break up function descriptions (using more than one paragraph is perfectly okay ;-)
- make the reference a bit more inviting to non-language-lawyers
- use “inverted pyramid” style a bit more often (brief summary followed by description followed by minutiae)
- replace grammar sections with human-readable notation.
- provide a few examples here and there.
- use more paragraphs. whitespace isn’t a disease.
- clean up the vocabulary; no need to use formal words when non-formal words would work
- use descriptive text when describing what things do, not prescriptive (i.e. use “gets the value” rather than “get the value”)
- avoid hyperbole (“the possibilities are endless”), odd or overly formal language, and bland examples (“foobar”?). also see the Style section on this page.