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

31–40 of 46 posts

Re: Rust docs team is no more

#31

Post by steveklabnik »

cwzwarich wrote: post #29
steveklabnik wrote: post #26

Earlier quoted context omitted.

mrustc has implemented a significant portion of the language, without a formal spec. It's at least advanced enough to compile the compiler. The biggest feature missing is borrowcheck.

I don't mean a formal spec. Rust is much too complicated and asymmetric to have a formal spec of the kind that exists for other languages (e.g. Standard ML), at least using current specification methodology. It doesn't even have an informal spec, which would be required to have a real attempt at multiple compatible implementations.

I hear what you're saying, but at the same time, mrustc is almost a counterexample of that. And we have real counterexamples in other languages too; Ruby and Python, for example.

(My understanding of mrustc and borrowck is that it's not implemented because the primary initial goal is bootstrapping rustc, not being a general rust compiler.)

Re: Rust docs team is no more

#32

Post by cwzwarich »

saagarjha wrote: post #27
cwzwarich wrote: post #19

Earlier quoted context omitted.

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.

Those are both core features of Rust, though, so any alternative implementation all but has to have them as that is the first thing anyone using it will be looking for.

Of course you need to have them, but there's no specification of their behavior, so your only hope at compatibility is reverse-engineering the existing implementation (or just reading its code).

Re: Rust docs team is no more

#33

Post by gpm »

Traster wrote: post #13

That feeling when you're done with writing documentation but you just can't shake the impulse to document that fact.

That feeling when you're documenting that someone made a HN comment documenting the blog post that documented the completion of the documentation.

Re: Rust docs team is no more

#34

Post by asdfman123 »

gpm wrote: post #33
Traster wrote: post #13

That feeling when you're done with writing documentation but you just can't shake the impulse to document that fact.

That feeling when you're documenting that someone made a HN comment documenting the blog post that documented the completion of the documentation.

See, all you need for job security is to create a recursive documentation procedure.

Re: Rust docs team is no more

#35

Post by penagwin »

asdfman123 wrote: post #34
gpm wrote: post #33

Earlier quoted context omitted.

That feeling when you're documenting that someone made a HN comment documenting the blog post that documented the completion of the documentation.

See, all you need for job security is to create a recursive documentation procedure.

Somebody should write this down!

Re: Rust docs team is no more

#36

Post by hiccuphippo »

scabarott wrote: post #30
Townley wrote: post #18

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 wit…

Did I read that wrong? It didn't sound like a 'switch'. It sounded more like someone quitting out of frustration and docs now ad-hoc with no clearly organized responsibility

It didn't sound like quitting to me, it was more like syncing the organization on paper with the reality. The team was one person and that person will continue what they do, only there's no reason to call it a team.

Re: Rust docs team is no more

#37

Post by scottlamb »

Townley wrote: post #18

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 wit…

I think you need both. You're not going to get a documentation team to successfully write API docs for every nook and cranny of the codebase if those nook and crannies' respective coders are uninterested. But you're also not going to get a bunch of coders whose main job is extending the language to write the Rust Book on the side. To me good documentation means that both those things exist.

Re: Rust docs team is no more

#38

Post by daveFNbuck »

Zenst wrote: post #16
Traster wrote: post #13

That feeling when you're done with writing documentation but you just can't shake the impulse to document that fact.

More so when we are in a time when people have the time to document things.

Not everyone has a bunch of free time right now. People working on software tend to be able to work from home.

Re: Rust docs team is no more

#39

Post by Scuds »

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.

I know... dotnet and Go aren't exactly hurting for effort for things like docs and tooling that take a project from good to great.
Post reply on HN