Consolidate Documentation (Remove RustByExample.com or The Book and References)

documentation
1

After using Rust for 2 months now I am increasingly finding myself going back and forth between the following in order to find documentation or examples on how to do something:

http://doc.rust-lang.org/book/ http://doc.rust-lang.org/std/index.html http://rustbyexample.com/ http://doc.rust-lang.org/reference.html

I go to these sources because I know they are official. I have found some of these are better updated than others and/or provide better information.

If I still can’t find the information I need I will reach out to Stack Overflow, Reddit, IRC.

I would like to see a consolidated source of at least official documentation.I think Rust does a good job of organizing and cleaning itself up in terms of source code. Doing the same with the documentation would be well received!

2

These all have a different purpose:

  • book & Rust by example: these are the two learning resources, and they’re for the two big styles of learning: longform writing and tons-of examples
  • std/index.html : this is the API documentation for the standard library.
  • reference.html : this is the ‘specification’, which is very out of date at the moment. I’m working on it during the beta period.
3

Each may have a different purpose conceptually but in reality they all contain useful information that all put together gives a better and more whole picture. Furthermore, isn’t it a nightmare keeping different documents up to date? The standard API docs are just about perfect because they are searchable and have a good mixture of explanation and examples. However, since other sources exist, I would like to see this organized into one location.

Some examples of the problem

  • The Book has longform writing but also has several examples. It also usually links to the API documentation or other references throughout a particular section.
  • RustByExample contains lots of stuff the Book does not. For example, I could not find anything about HashMap in the Book(and had no way to search) for it if it was bundled in somewhere I would not expect.
  • RustByExample has a section about Threads. The Book’s section is called Tasks.
  • http://rustbyexample.com/staging/hash.html has a broken link at the bottom to Wikipedia

To me, the ideal document would have the 1 2 3 4 5 hierarchy the Book has and filled in with the RustByExample hierarchy within those levels. The body of the particular topic would consist of what the Book has. The top has a table with links to the API(if applicable) or general domain information. More examples and Reference(specification) is folded into this document as it’s own section.

Eliminate the Reference document(as a separate doc). Eliminate RustByExample.com or have it point to this new document.

Keep documentation DRY the same as you would code.

Example of a section:

Iterators

API: http://doc.rust-lang.org/std/iter/ Domain Info: http://en.wikipedia.org/wiki/Iterator

Futher Reading Specification: Spec(bottom of page) More Examples: Examples(bottom of page)

Let’s talk about loops. …

4

I pretty much only use the API reference. There are places where more examples would be nice (can’t call specifics to mind right now), but I’ve generally found what I’m looking for in there.

5

I’m constantly working on more examples, but have been waiting until things stabilize to add tons more. Now that we’re getting there, I’m ramping up my efforts in this regard.

1 Like
6

First a question: what are the plans for rustbook? Probably should be a separate topic but thought I’d ask as it applies to my opinion.

Yes to combining rust book and rust by example. Std docs we can link to correct references but not entirely sure how they can be combined.

Regarding learning from long form or examples – This is kinda trivial as it is just a toggle switch in the display to see full explanation or a smaller one.

  • In the long run combining both it provides better safety from one source rotting away.
  • Also not duplicating efforts with explaining same examples
    • As an example range still used on rustbyexample and book updated with range notation ..
  • Currently book examples cannot be run in the browser
    • If they are fixed i believe they will open a new window to play.rust-lang like the std docs do, however i prefer having the editor in the same page so that you do not lose your focus.
  • Also currently imho the gitbook output looks much better

Which brings me to my initial question the plans for rustbook.

  1. Are we using rustbook just for having a consistent ui/feeling/theme with the std docs?
  2. is rustbook going to remain separate or will it become part of rustdoc?
  3. what is the final vision for rustbook? just used to build rust book?
7

I would prefer if there was only a single source of documenation. Everything should be part of what currently the API docs are.

The tutorial can be added as separate resources to rustdoc. The Reference and advanced parts of the bookcan be added in the same way. Rustbyexample examples can be added where they fit in the api since they do not have a particular order.

The ideal would be something like the python docs for me.

8

This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.