bevyengine / bevyengine/bevy

`bevy` Crate Module Documentation Standardization

Open
#21,126 2 comments 0 reactions 0 assignees View on GitHub
A-Cross-Cutting C-Docs D-Straightforward S-Ready-For-Implementation
Dominant language
Rust
Stars
48.2k
Forks
4.8k
Avg merge
3d 22h
Merged PRs (30d)
161

Description

## How can Bevy's documentation be improved?

The module section of the [docs.rs page](https://docs.rs/bevy/0.17.0-rc.1/bevy/index.html) for the main `bevy` crate could use some cleanup.

- Because `bevy` is just a container crate pulling together smaller sub-crates, the module documentation is actually crate documentation.
- This means that sometimes you see phrases like "this crate" or explanations that the crate provides functionality for the larger bevy ecosystem.
- Some modules hyperlink bevy.org while others do not, which is inconsistent, and "bevy" is used interchangeably with "The Bevy Game Engine".

## What should it look like instead?

Rust [`std` modules](https://doc.rust-lang.org/std/) provide a clear example on what this should be lookin like.

- They're concise, typically under 10 words.
- They do not refer to Rust as a whole, except for the prelude module.
- They are formatted as a complete sentence.

I'll take this on if it's determined that its OK to work on this. :3

Contributor guide

Open the contributing guide

Research direction

Start by reviewing the module documentation shown on the main bevy crate's docs.rs page and compare its style with Rust's std module documentation. Standardization is done when module descriptions are concise complete sentences with consistent terminology and consistent bevy.org linking, without referring to the container crate as an individual library.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
50/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.