Documentation

Integrating documentation into the language is crucial. The barrier to adding documentation should be low and good tooling should be able to weave together documentation with the static information available in the code. I would also like to encourage documenting "why does this code exist and who would call it" over "what does it do".

I'm starting to think that this should be merged with testing and the two exist on a spectrum.

Usage

This is the basic documentation, how a function is called, what it is intended to do.

Case Logic

Present either in place or as a pointer to a larger document; often at a low level it is difficult to see a larger picture. It is important to have higher level documentation. One risk here is that high level documentation can drift. It would be good to have a review process that can attest that documentation is up to date, even if it hasn't changed. And the ability to highlight documentation that may be out of date.

Examples

I like how Go does this of providing examples that function as both tests and documentation.

Mapping

References are bidirectional. Static tools are good at "forward referencing", but sometimes it's just as crucial to know upstream invocations. With in a package this can be done easily enough, but it may be worth including a way to reference "upstream packages" as a way to indicate callers that may be broken by changes.

This could be as simple as providing a bit of markup tooling. Referencing "foo.Bar" in the comment will create a link if foo is imported. If not, it can be doc imported with a doc comment by using it's import path.