Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Rust docs team is no more

blog.rust-lang.org

Post reply on HN
Print view View original

11–20 of 46 posts

Re: Rust docs team is no more

#11

Post by saxonww »

hu3 wrote: post #6

Begs the question: Why isn't Mozilla funding this? > At this point, the only person really writing docs is me, and I haven't had a ton of time lately either. So we haven't had a docs team meeting since August of 2018. There also aren't really docs RFCs these days. As such, this blog post isn't really announcing the end of the docs team as much as it is describing what is already true today.

They used to, but it looks like that came with its own set of problems: https://words.steveklabnik.com/thank-u-next

Re: Rust docs team is no more

#12

Post by phkahler »

ocdtrekkie wrote: post #7
hu3 wrote: post #3

Earlier quoted context omitted.

"done" in what sense? I don't think documentation of a living project is ever finished.

Sure, but it sounds like docs are now updated by the relevant developers. The "docs team" sounds more like a project team to overhaul the state of docs at the time, which is now complete.

We can hope that the language itself is similarly declared "done" at some point. That would be in contrast to C++ for example, where it's the job of a bunch of people to keep making changes ad nausium until it starts to crumble.

Re: Rust docs team is no more

#14

Post by tannhaeuser »

mfer wrote: post #10

&tldr; The docs team created filled in the gaps where they were needed when it was created. Now, the teams making the code changes handle their own docs and doc changes. There is no longer a need for a docs only team. So, instead of having a dedicated team for docs the load has shifted to the teams responsible for the code. Sounds like a reorg more than anything.

Out of curiosity, how many people are working on Rust as permanent employees or otherwise paid by Mozilla? I thought Rust is mainly developed by individual contributors but "load has shifted to the teams responsible for the code" and "reorgs" sure sounds like there's some kind of hierarchical leverage and long-term planning in place.

Re: Rust docs team is no more

#15

Post by thejosh »

mikece wrote: post #2

An example of a project that is "done?"

Elixir? José Valim, announcing the just-released Elixir v1.9:

… releases was the last planned feature for Elixir. We don’t have any major user-facing feature in the works nor planned. I know for certain some will consider this fact the most excing part of this announcement!

[1] https://changelog.com/news/the-elixir-language-is-now-featur...

Re: Rust docs team is no more

#18

Post by Townley »

To get good documentation, you can either take a documentation expert (they exist and they're worth their weight in gold) and teach them the relevant part of the code base, or take the code author and teach them to write good docs. In my opinion, the second approach is best because the code author has the nuanced familiarity necessary to provide high-level context to an end-user.

This switch by Rust seems in line with that thinking. The Rust community, through no accidents, has incredible standards when it comes to documentation. Now that the feature teams have learned to write docs that live up to that standard (a skill as valuable as writing tests IMO) it makes sense for them to do so.

Re: Rust docs team is no more

#19

Post by cwzwarich »

phkahler wrote: post #12
ocdtrekkie wrote: post #7

Earlier quoted context omitted.

Sure, but it sounds like docs are now updated by the relevant developers. The "docs team" sounds more like a project team to overhaul the state of docs at the time, which is now complete.

We can hope that the language itself is similarly declared "done" at some point. That would be in contrast to C++ for example, where it's the job of a bunch of people to keep making changes ad nausium until it starts to crumble.

Would a Rust spec that actually allows multiple compatible implementations actually be simpler than the C++ spec? There has only ever been one real Rust implementation, and a lot of Rust behaviors are just arbitrary implementation decisions, especially with subtyping in the type system and the borrow checker.
Post reply on HN