Rust's
Documentation

A proposal

By @steveklabnik

Slides: http://steveklabnik.github.io/rust_documentation/

Intro

I want to see a 30 minute 'introduction to Rust.'

Problem:

Do you know C++?

Solution:

Assume that you know systems programming, but acknowledge it.

Spec

It's like static typing, for the language.

Spec

The one we have is bad.

Spec

A spec allows you to answer 'bug or not?'

Spec

Bonus points: executable

Spec

I want to see 'PEP' for Rust.

Guides

Specific, cross-cutting topics.

Guides

We have a really confusing 'tutorial' and then 'tutorials.'

Guides

More in-depth than the tutorial, but not exhaustive.

Guides

Guides are for best practices, common patterns, and use cases.

Guides

Esoterica belongs in the spec only!

Examples

  • The Pointer Guide
  • The Syntax Guide
  • Rust for C++ Programmers
  • Systems programming for newbies?

API

Low-level details.

API

Pretty good!

API

Ideally, the guides would cross-reference the API tutorials.

API

Traits vs. Implementations?

API

Every function should have examples.

Meta

... sort of.

Meta

Documentation about the compiler itself.

Meta

"How to Contribute to Rust."

Meta

Governance

Meta

Style guides

Meta

... basically, the wiki. Which is terrible.

Style

Mean, but for your own good.

Style

The biggest failure of our documentation today is the same failure most documentation written by programmers has.

Style

Nobody cares about your weird edge cases.

Style

Sorry. Anyway.

Style

Resisting the urge to add strange information is crucial. That's what the spec is for.

Style

All documentation should be focused on how we're great.

Style

Case study: Ruby on Rails

Style

A vibrant blogging community leads to poor documentation.

Thanks!

@steveklabnik

Slides: http://steveklabnik.github.io/rust_documentation/