I would welcome such an effort, and suggest that it live as its own project, outside of the Rust repo. We really aren't set up currently to handle rapid and frequent documentation changes. Once it gets to a reasonable level of maturity we could then give it a mention from the main tutorial, and then once it's ready we could replace the current tutorial entirely.
On Thu, Nov 14, 2013 at 11:58 AM, Gaetan <gae...@xeberon.net> wrote: > I would love helping on this matter, I'm use to setting up automatic > documentation generation (rst, sphinx, doxygen,...). > > ----- > Gaetan > > > > 2013/11/14 Philip Herron <redbr...@gcc.gnu.org> > >> I would defineltly like to see a clone of the python tutorial because it >> really does it so well going inch by inch building up what way things work >> i am not a web developer but would love to write content i wonder is it >> possible to start a github project for this using sphinx i think it uses >> isn't it? >> >> >> On 14 November 2013 15:38, Corey Richardson <co...@octayn.net> wrote: >> >>> On Thu, Nov 14, 2013 at 10:03 AM, Daniel Glazman >>> <d.glaz...@partner.samsung.com> wrote: >>> > The Tutorial is the entry point for all people willing to investigate >>> > Rust and/or contribute to Servo. I think that document is super >>> > precious, super-important. Unfortunately, I don't think it is really a >>> > tutorial but only a lighter manual. Examples are here even more >>> > important than in the case of the Manual above. A good Tutorial is >>> > often built around one single programming task that becomes more and >>> > more complex as more features of the language are read and >>> > known. Furthermore, the Tutorial has clearly adopted the language >>> > complexity of the reference manual, something that I think should be >>> > in general avoided. I also think all examples should be buildable >>> > and produce a readable result on the console even if that result is a >>> > build or execution error. That would drastically help the reader. >>> > >>> > All in all, I think the Tutorial needs some love and probably a >>> > technical writer who is not working on the guts of Rust, someone who >>> > could vulgarize the notions of the Manual into an easy-to-read, >>> > simple-to-experiment, step-by-step tutorial and avoiding in general >>> > vocabulary inherited from programming language science. >>> > >>> >>> I agree, partially. I think "Rust for Rubyists" fills this role quite >>> well for now. Generally I think the language tutorial should not try >>> to hide complexity or paper over things, at the very least so it can >>> be complete and correct. I think the Python tutorial is a good >>> benchmark. We might even be able to rip off the Python tutorial's >>> structure wholesale. >>> >>> The "on-boarding" process is still very rough. Maybe some sort of >>> live-comment system would work well for finding pain points, where one >>> can add comments/feedback while reading the tutorial. >>> _______________________________________________ >>> Rust-dev mailing list >>> Rust-dev@mozilla.org >>> https://mail.mozilla.org/listinfo/rust-dev >>> >> >> >> _______________________________________________ >> Rust-dev mailing list >> Rust-dev@mozilla.org >> https://mail.mozilla.org/listinfo/rust-dev >> >> > > _______________________________________________ > Rust-dev mailing list > Rust-dev@mozilla.org > https://mail.mozilla.org/listinfo/rust-dev > >
_______________________________________________ Rust-dev mailing list Rust-dev@mozilla.org https://mail.mozilla.org/listinfo/rust-dev
