Rust Community Wiki:Writing Guidelines

Rust Community Wiki Writing GuidelinesEdit

The Rust Community Wiki strives to be clear, professional, and useful to the rust-lang community. In that regard, contributors of this wiki should try to keep in mind some guidelines, that we will try to describe in this article.

Naming pagesEdit

It is well known that naming can be a daunting task to the day-to-day programmer, and naming pages on a wiki is no different. Some key takeaways:

  • Names should be both as specific and as short as possible. Avoid using questions. Example: "How to handle errors" should be "Error management"
  • Avoid acronyms and other shortened names. You can add a redirect to the page with the full name instead. Example: DBMS should redirect to "Database Management System".

TemplatesEdit

The templates that are useful on this wiki are:

Useful "Special" pagesEdit

Writing guidelinesEdit

Duplicate contentEdit

Avoid duplicating both official content (e.g. Rust book) and content that can be found elsewhere on this wiki.

For wiki content, prefer linking to the page instead. It is fine to include a short summary as well.

For official content, it is fine to complement and improve on the official book, standard library, and other resources; but you should avoid rewriting what has already been written. For example the "Iterator" page: you can link to the Rust book chapter and API reference, but you can also expand on many other topics that the official content does not cover (e.g. the difference between IntoIterator and Iterator, Iter and Iterator, or the other less known traits such as FusedIterator, ExactSizeIterator, DoubleEndedIterator, etc. You may also write about related crates such as itertools.).

Whenever related content exists externally (e.g. a blog post or study), you may link it in a "Related content" section. Or if the content is notable, you can mention it in-text.

Do not feel limited by what you can or cannot write. If you feel it is necessary for a page's consistency to rewrite small parts of official content, do so. Even if you don't want to step on official resources, a quick search in the wiki and the official resources will quickly show what has been written in depth about, what has been left out of the more experienced users to discover.

On biased statementsEdit

This wiki aims to be professional, but some pages, such as crate comparisons pages, may be on the controversed side.

When writing statements, especially ones that might raise controversy, try to back them up with a source. For example "nightly is the most used compiler version" doesn't give enough information and is hardly checkable by a peer. However, "According to the Rust Users 2018 survey, 30% of active users use the nightly version of cargo and rustc" is clear, checkable, and no one can argue about it.

Surveys will always be more suited measuring popularity than any of crates.io's stats. If you feel like one survey is missing, running a fair one yourself and using it in a page you are writing is always an option.

On ecosystem comparisonsEdit

It is allowed to write articles which have the only purpose of comparing an ecosystem of crates or frameworks.

When doing this, it is generally preferred to use tables. It is easier to compare features and aspects in an organized table, rather than in a huge chunk of text.

Try to be as neutral as possible:

  • List facts instead of opinions. E.g. "crate my_collection doesn't have serde bindings" is a neutral and important fact to not omit, while "my_collection is a mess documentation-wise" is an opinion.
  • Avoid ranking crates, even by popularity. It is OK to include popularity info based on an external source such as crates.io downloads or a survey. But avoid ordering them by popularity.
  • Try to mention the crate status and development status for each of them.
    • "Experimental", "Stabilizing", "Stable" can be used to note the crate's status
      • Experimental: the crate might get a total API overhaul or major change without any guarantee for stability.
      • Stabilizing: the crate is not quite stable in the semantic versioning sense, but an effort is done to make sure the breaking changes are the less impactful possible.
      • Stable: the crate is stable, updates will rarely break previous code, and the current API will not change, but it might have new features in the future.
    • "Actively developed", "Passively maintained", "Deprecated", and "Abandoned" can used to note the development status.
      • Actively developed: the crate is currently being developed by its creators: fixes and new features are added regularly.
      • Passively maintained: the crate is neither deprecated nor abandoned, but no new features will be added by the creators. Pull requests will still be reviewed and merged as usual.
      • Deprecated: the authors think the usage of this crate is discouraged. There might be a link to a newer or better crate with the same features. Fixes and new features might be reviewed, but there won't be any new development for this crate.
      • Abandoned: the author abandoned this crate and is not reviewing issues or potential fixes.
  • If you add ecosystem-specific columns in your tables, try to add a description above on what them mean.
  • Add and keep deprecated crates in your comparisons, do not remove them. If a user reads your comparison and notices a crate they have heard of is deprecated, they will keep a mental note about it. If it's not mentioned at all, they might wonder what was the crate about.
Crate comparison table example
crate name Status

(latest version)

Development Status

(last updated)

serde derive Notes
my_collection Experimental (0.3.0) Abandoned (2015) No
simple_collection Stabilizing (0.20.9) Actively developed (May 2020) Coming in 0.21 Uses a mix of Rust and the external C library [insert C library example]
complex_collection Stable (1.0.89) Passively maintained (Jan 2020) Yes Used officially by [insert big company name]. Most popular crate in this category as of 2019 according to crates.io