Re: [rust-dev] Rust docs for 0.8: No idea what this does
You realize you're using a 3 month old unsupported release of a pre-alpha language, right? Anyway I don't know how those got promoted to doc comments, they used to just be comments. On Mon, Jan 13, 2014 at 8:25 PM, Andrew Pennebaker andrew.penneba...@gmail.com wrote: Who wrote these 0.8 docs: http://static.rust-lang.org/doc/0.8/extra/getopts/struct.Matches.html Fortunately, they're much improved in 0.9. -- Cheers, Andrew Pennebaker www.yellosoft.us ___ 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
Re: [rust-dev] Rust docs for 0.8: No idea what this does
After seeing the title of this email I hoped that it was me. Regardless there's no need to blame anyone. Somebody was nice enough to go through and add docs and put in a FIXME. All part of the process. On 01/13/2014 05:25 PM, Andrew Pennebaker wrote: Who wrote these 0.8 docs: http://static.rust-lang.org/doc/0.8/extra/getopts/struct.Matches.html Fortunately, they're much improved in 0.9. -- Cheers, Andrew Pennebaker www.yellosoft.us http://www.yellosoft.us ___ 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
Re: [rust-dev] Rust docs for 0.8: No idea what this does
The explanation was already given by Corey. It was a normal comment but mistakenly got promoted by someone to a doc comment. Perhaps it was a search and replace gone wrong. At least it was amusing :) jack. On Mon, Jan 13, 2014 at 7:17 PM, Andrew Pennebaker andrew.penneba...@gmail.com wrote: I won't bother using git blame, it's just weird to see such comments in doc files. If you don't know what something does, why not leave it blank? On Jan 13, 2014 9:03 PM, Steve Klabnik st...@steveklabnik.com wrote: No reason to be so harsh, especially since they've been improved. There is a way you can find out, but I'm not telling you. I love 'these docs are poor' comments, as they help me figure out what needs to be improved, but there's no reason to pick something that's already been fixed and try to make someone feel bad. ___ 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
Re: [rust-dev] Rust docs
That was my point on another thread. I think it's best to have a top-bottom approach, ie, decribe everything else BUT the language first (how crates works, how to compile, how to test,...) and then introduce the memory concepts, etc. I think the technical writer is a full time job, how to present things properly is not easy to do. He may have better way of introducing the language. I tend to agree with the assertion that its not a level of quality we can achieve with collaborating works, sadly. - Gaetan 2013/11/19 Thad Guidry thadgui...@gmail.com I tend to agree with this, think that a collaborative approach is unlikely to produce a consistent and high quality tutorial. I don't want to discourage anybody but my current opinion is that we should hire an experienced technical writer to do this piece especially, with input from the wider community. Where I think collaboration is more likely to produce something nice is in a 'cookbook' style document, of which several people have already worked on seperately. Also of course API docs and the reference manual are places where individuals can plug in their own sections without impacting the overall narrative flow. So I spent this evening going through the tutorial (.08). As an outsider to Rust, I can tell you it does not fit any model of a tutorial, but instead is an elongated language reference broken down into feature sections. Which is highly useful in its design, and does say This tutorial assumes that the reader is already familiar with one or more languages in the C family. Understanding of pointers and general memory management techniques will help. BUT... It was not until section 17, that I finally met with a simple program that could compile. That was 2 1/2 hours later before I was able to DO SOMETHING. I would encourage the Mozilla team to hire a technical writer as Brian suggests, that would turn the tutorial upside down... Start with something fun and entertaining in under 10 or 20 lines of Rust, that would amuse and provide hackability to tweak and play with values, mutability, and seeing the stack pop itself (half the developers in the world, do not know or have to worry about a stack..but of course should in any decent systems language :-) ), and then introduce garbage collecting, etc. Introduce compile-able examples from the start, and continue with working examples that actually produce errors and let the user come to grips with the syntax compiler error output, while coaching them through fixing the errors, and learning the do's and don'ts of Rust's current best practices. That would be a mighty fine tutorial and the makings of a book for Rust itself. 2 cents and a haircut and I wish the team tremendous success on finding a talented writer, -- -Thad +ThadGuidry https://www.google.com/+ThadGuidry Thad on LinkedIn http://www.linkedin.com/in/thadguidry/ ___ 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
Re: [rust-dev] Rust docs
Hello, I would like to share my experience about the Rust doc and the tutorial. I've just started to learn Rust and I've decided to use it on a project I work on. Like everybody I read the Rust tutorial. It's not a really a tutorial for beginner but it do a good job in presenting Rust and its mains concept. I found other tutorial on the web and in my opinion what is missing the more is sample code. The Rust lib is huge and there is no code. In my project I have to use Json serialization. So I wanted to use the json lib in extra lib and I really spend some time to make a simple code works. I was very near to write my own lib. json.rs is a little complicated for a newbie. There are some test case at the end but it tests the lib and not what I want to do with it. For example there is no serialization of an object. I search the web and I found some old example (not compatible with the master lib) and no object serialization. So what I think is that it would be great is to construct a repository of sample code of the Rust lib that show how to use the lib. I'm ok to write and maintain some sample like one on json. I think it would be great to host all these sample in the same repository and to have the same organization for all sample. The second reason tu use a share repository is that the sample has to be made in the spirit of Rust to help understand it. For that the sample must be checked and modified by more experienced rust developer. It's easier when the code is in a common repository. Pḧilippe ___ Rust-dev mailing list Rust-dev@mozilla.org https://mail.mozilla.org/listinfo/rust-dev
Re: [rust-dev] Rust docs
I think it's better to enhance the extra::json lib itself and write proper module documentation, with samples, use case etc. My reference is the QT documentation. You never open and samples or even the QT source code, everything is in the module documentation. - Gaetan 2013/11/19 Philippe Delrieu philippe.delr...@free.fr Hello, I would like to share my experience about the Rust doc and the tutorial. I've just started to learn Rust and I've decided to use it on a project I work on. Like everybody I read the Rust tutorial. It's not a really a tutorial for beginner but it do a good job in presenting Rust and its mains concept. I found other tutorial on the web and in my opinion what is missing the more is sample code. The Rust lib is huge and there is no code. In my project I have to use Json serialization. So I wanted to use the json lib in extra lib and I really spend some time to make a simple code works. I was very near to write my own lib. json.rs is a little complicated for a newbie. There are some test case at the end but it tests the lib and not what I want to do with it. For example there is no serialization of an object. I search the web and I found some old example (not compatible with the master lib) and no object serialization. So what I think is that it would be great is to construct a repository of sample code of the Rust lib that show how to use the lib. I'm ok to write and maintain some sample like one on json. I think it would be great to host all these sample in the same repository and to have the same organization for all sample. The second reason tu use a share repository is that the sample has to be made in the spirit of Rust to help understand it. For that the sample must be checked and modified by more experienced rust developer. It's easier when the code is in a common repository. Pḧilippe ___ 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
Re: [rust-dev] Rust docs
Also, what we set up in our scrum team is targetted doc stories inside each sprint. Let's say that over the next month, the objective is to improve a set of module doc, ie, a list of very useful std or extra lib that is not properly documented. For instance, the next month we target on improving json or extra::path, and enhance them until they become golden star level. And the next month or sprint, we focus on other modules It's easier to focus people like this that just telling you can take whichever module you want and improve them. It just work better, we discovered. - Gaetan 2013/11/19 Gaetan gae...@xeberon.net I think it's better to enhance the extra::json lib itself and write proper module documentation, with samples, use case etc. My reference is the QT documentation. You never open and samples or even the QT source code, everything is in the module documentation. - Gaetan 2013/11/19 Philippe Delrieu philippe.delr...@free.fr Hello, I would like to share my experience about the Rust doc and the tutorial. I've just started to learn Rust and I've decided to use it on a project I work on. Like everybody I read the Rust tutorial. It's not a really a tutorial for beginner but it do a good job in presenting Rust and its mains concept. I found other tutorial on the web and in my opinion what is missing the more is sample code. The Rust lib is huge and there is no code. In my project I have to use Json serialization. So I wanted to use the json lib in extra lib and I really spend some time to make a simple code works. I was very near to write my own lib. json.rs is a little complicated for a newbie. There are some test case at the end but it tests the lib and not what I want to do with it. For example there is no serialization of an object. I search the web and I found some old example (not compatible with the master lib) and no object serialization. So what I think is that it would be great is to construct a repository of sample code of the Rust lib that show how to use the lib. I'm ok to write and maintain some sample like one on json. I think it would be great to host all these sample in the same repository and to have the same organization for all sample. The second reason tu use a share repository is that the sample has to be made in the spirit of Rust to help understand it. For that the sample must be checked and modified by more experienced rust developer. It's easier when the code is in a common repository. Pḧilippe ___ 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
Re: [rust-dev] Rust docs
I am willing to help also but i find it quite hard to setup the environnement properly. Is these a tutorial for this point? Le 19 nov. 2013 14:58, Philippe Delrieu philippe.delr...@free.fr a écrit : I'am ok to add sample code in json.rs. how can I do? I think I will have other sample code for other lib in a few days. I'll wait that the lib is open to doc enhancement or I put it as it come and how can it be managed. Philippe Le 19/11/2013 14:48, Gaetan a écrit : Also, what we set up in our scrum team is targetted doc stories inside each sprint. Let's say that over the next month, the objective is to improve a set of module doc, ie, a list of very useful std or extra lib that is not properly documented. For instance, the next month we target on improving json or extra::path, and enhance them until they become golden star level. And the next month or sprint, we focus on other modules It's easier to focus people like this that just telling you can take whichever module you want and improve them. It just work better, we discovered. - Gaetan 2013/11/19 Gaetan gae...@xeberon.net I think it's better to enhance the extra::json lib itself and write proper module documentation, with samples, use case etc. My reference is the QT documentation. You never open and samples or even the QT source code, everything is in the module documentation. - Gaetan 2013/11/19 Philippe Delrieu philippe.delr...@free.fr Hello, I would like to share my experience about the Rust doc and the tutorial. I've just started to learn Rust and I've decided to use it on a project I work on. Like everybody I read the Rust tutorial. It's not a really a tutorial for beginner but it do a good job in presenting Rust and its mains concept. I found other tutorial on the web and in my opinion what is missing the more is sample code. The Rust lib is huge and there is no code. In my project I have to use Json serialization. So I wanted to use the json lib in extra lib and I really spend some time to make a simple code works. I was very near to write my own lib. json.rs is a little complicated for a newbie. There are some test case at the end but it tests the lib and not what I want to do with it. For example there is no serialization of an object. I search the web and I found some old example (not compatible with the master lib) and no object serialization. So what I think is that it would be great is to construct a repository of sample code of the Rust lib that show how to use the lib. I'm ok to write and maintain some sample like one on json. I think it would be great to host all these sample in the same repository and to have the same organization for all sample. The second reason tu use a share repository is that the sample has to be made in the spirit of Rust to help understand it. For that the sample must be checked and modified by more experienced rust developer. It's easier when the code is in a common repository. Pḧilippe ___ 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
Re: [rust-dev] Rust docs
I'am ok to add sample code in json.rs. how can I do? I think I will have other sample code for other lib in a few days. I'll wait that the lib is open to doc enhancement or I put it as it come and how can it be managed. Philippe Le 19/11/2013 14:48, Gaetan a écrit : Also, what we set up in our scrum team is targetted doc stories inside each sprint. Let's say that over the next month, the objective is to improve a set of module doc, ie, a list of very useful std or extra lib that is not properly documented. For instance, the next month we target on improving json or extra::path, and enhance them until they become golden star level. And the next month or sprint, we focus on other modules It's easier to focus people like this that just telling you can take whichever module you want and improve them. It just work better, we discovered. - Gaetan 2013/11/19 Gaetan gae...@xeberon.net mailto:gae...@xeberon.net I think it's better to enhance the extra::json lib itself and write proper module documentation, with samples, use case etc. My reference is the QT documentation. You never open and samples or even the QT source code, everything is in the module documentation. - Gaetan 2013/11/19 Philippe Delrieu philippe.delr...@free.fr mailto:philippe.delr...@free.fr Hello, I would like to share my experience about the Rust doc and the tutorial. I've just started to learn Rust and I've decided to use it on a project I work on. Like everybody I read the Rust tutorial. It's not a really a tutorial for beginner but it do a good job in presenting Rust and its mains concept. I found other tutorial on the web and in my opinion what is missing the more is sample code. The Rust lib is huge and there is no code. In my project I have to use Json serialization. So I wanted to use the json lib in extra lib and I really spend some time to make a simple code works. I was very near to write my own lib. json.rs http://json.rs is a little complicated for a newbie. There are some test case at the end but it tests the lib and not what I want to do with it. For example there is no serialization of an object. I search the web and I found some old example (not compatible with the master lib) and no object serialization. So what I think is that it would be great is to construct a repository of sample code of the Rust lib that show how to use the lib. I'm ok to write and maintain some sample like one on json. I think it would be great to host all these sample in the same repository and to have the same organization for all sample. The second reason tu use a share repository is that the sample has to be made in the spirit of Rust to help understand it. For that the sample must be checked and modified by more experienced rust developer. It's easier when the code is in a common repository. Pḧilippe ___ Rust-dev mailing list Rust-dev@mozilla.org mailto: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
Re: [rust-dev] Rust docs
I am a student and thinking to write tutorial for it . * Laxmi Narayan Patel* * MCA NIT Durgapur ( Final year)* * Mob:-8345847473* On Tue, Nov 19, 2013 at 10:33 AM, Thad Guidry thadgui...@gmail.com wrote: I tend to agree with this, think that a collaborative approach is unlikely to produce a consistent and high quality tutorial. I don't want to discourage anybody but my current opinion is that we should hire an experienced technical writer to do this piece especially, with input from the wider community. Where I think collaboration is more likely to produce something nice is in a 'cookbook' style document, of which several people have already worked on seperately. Also of course API docs and the reference manual are places where individuals can plug in their own sections without impacting the overall narrative flow. So I spent this evening going through the tutorial (.08). As an outsider to Rust, I can tell you it does not fit any model of a tutorial, but instead is an elongated language reference broken down into feature sections. Which is highly useful in its design, and does say This tutorial assumes that the reader is already familiar with one or more languages in the C family. Understanding of pointers and general memory management techniques will help. BUT... It was not until section 17, that I finally met with a simple program that could compile. That was 2 1/2 hours later before I was able to DO SOMETHING. I would encourage the Mozilla team to hire a technical writer as Brian suggests, that would turn the tutorial upside down... Start with something fun and entertaining in under 10 or 20 lines of Rust, that would amuse and provide hackability to tweak and play with values, mutability, and seeing the stack pop itself (half the developers in the world, do not know or have to worry about a stack..but of course should in any decent systems language :-) ), and then introduce garbage collecting, etc. Introduce compile-able examples from the start, and continue with working examples that actually produce errors and let the user come to grips with the syntax compiler error output, while coaching them through fixing the errors, and learning the do's and don'ts of Rust's current best practices. That would be a mighty fine tutorial and the makings of a book for Rust itself. 2 cents and a haircut and I wish the team tremendous success on finding a talented writer, -- -Thad +ThadGuidry https://www.google.com/+ThadGuidry Thad on LinkedIn http://www.linkedin.com/in/thadguidry/ ___ 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
Re: [rust-dev] Rust docs
On 11/14/2013 01:08 PM, Daniel Glazman wrote: Honestly, I am not sure tutorial quality and automatic generation live well together. We hire tech evangelists for their ability to present well information and make messages percolate better, and similarly good doc requires good tech writers who only do that. As I said earlier, a tutorial is crucial material to attract people and I think writing talent, excellent presentation and correct readability are need for such a tutorial. When I say attract people or community, I am of course thinking of reaching critical masses for Rust-based projects, including Servo, and that requires making sure documentation material are good enough to self-generate a pool of potential hires. I tend to agree with this, think that a collaborative approach is unlikely to produce a consistent and high quality tutorial. I don't want to discourage anybody but my current opinion is that we should hire an experienced technical writer to do this piece especially, with input from the wider community. Where I think collaboration is more likely to produce something nice is in a 'cookbook' style document, of which several people have already worked on seperately. Also of course API docs and the reference manual are places where individuals can plug in their own sections without impacting the overall narrative flow. ___ Rust-dev mailing list Rust-dev@mozilla.org https://mail.mozilla.org/listinfo/rust-dev
Re: [rust-dev] Rust docs
I tend to agree with this, think that a collaborative approach is unlikely to produce a consistent and high quality tutorial. I don't want to discourage anybody but my current opinion is that we should hire an experienced technical writer to do this piece especially, with input from the wider community. Where I think collaboration is more likely to produce something nice is in a 'cookbook' style document, of which several people have already worked on seperately. Also of course API docs and the reference manual are places where individuals can plug in their own sections without impacting the overall narrative flow. So I spent this evening going through the tutorial (.08). As an outsider to Rust, I can tell you it does not fit any model of a tutorial, but instead is an elongated language reference broken down into feature sections. Which is highly useful in its design, and does say This tutorial assumes that the reader is already familiar with one or more languages in the C family. Understanding of pointers and general memory management techniques will help. BUT... It was not until section 17, that I finally met with a simple program that could compile. That was 2 1/2 hours later before I was able to DO SOMETHING. I would encourage the Mozilla team to hire a technical writer as Brian suggests, that would turn the tutorial upside down... Start with something fun and entertaining in under 10 or 20 lines of Rust, that would amuse and provide hackability to tweak and play with values, mutability, and seeing the stack pop itself (half the developers in the world, do not know or have to worry about a stack..but of course should in any decent systems language :-) ), and then introduce garbage collecting, etc. Introduce compile-able examples from the start, and continue with working examples that actually produce errors and let the user come to grips with the syntax compiler error output, while coaching them through fixing the errors, and learning the do's and don'ts of Rust's current best practices. That would be a mighty fine tutorial and the makings of a book for Rust itself. 2 cents and a haircut and I wish the team tremendous success on finding a talented writer, -- -Thad +ThadGuidry https://www.google.com/+ThadGuidry Thad on LinkedIn http://www.linkedin.com/in/thadguidry/ ___ Rust-dev mailing list Rust-dev@mozilla.org https://mail.mozilla.org/listinfo/rust-dev
[rust-dev] Rust docs
Hello rust-dev, I would like to make a comment I feel is important about both the Rust tutorial and manual. Please don't misunderstand me, no flame here, I am sending this message to help. I think good docs are extremely important to increase the size of a community, and in particular make more people contribute to Servo (the reason why I'm here). If the Reference Manual for Rust tries to be complete and does not try to avoid language complexity, it can be from time to time hard to read because of one thing: examples are not well or often enough explained and are often too complex given the section they belong too. It's for instance difficult for the reader to understand an example of section n that uses notions explained only in section n+4. 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. Best regards, /Daniel ___ Rust-dev mailing list Rust-dev@mozilla.org https://mail.mozilla.org/listinfo/rust-dev
Re: [rust-dev] Rust docs
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
Re: [rust-dev] Rust docs
Corey, Could we get that comments/feedback ability into the tutorial easily ? I agree that would be a good start in improving things. On Thu, Nov 14, 2013 at 9:38 AM, 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 -- -Thad +ThadGuidry https://www.google.com/+ThadGuidry Thad on LinkedIn http://www.linkedin.com/in/thadguidry/ ___ Rust-dev mailing list Rust-dev@mozilla.org https://mail.mozilla.org/listinfo/rust-dev
Re: [rust-dev] Rust docs
I've never setup such a system. I imagine it'd need some infrastructure in place. On Thu, Nov 14, 2013 at 11:21 AM, Thad Guidry thadgui...@gmail.com wrote: Corey, Could we get that comments/feedback ability into the tutorial easily ? I agree that would be a good start in improving things. On Thu, Nov 14, 2013 at 9:38 AM, 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 -- -Thad +ThadGuidry Thad on LinkedIn ___ Rust-dev mailing list Rust-dev@mozilla.org https://mail.mozilla.org/listinfo/rust-dev
Re: [rust-dev] Rust docs
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
Re: [rust-dev] Rust docs
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
Re: [rust-dev] Rust docs
And by replace I mean we could relegate the current tutorial to an advanced tutorial or somesuch. On Thu, Nov 14, 2013 at 12:30 PM, Benjamin Striegel ben.strie...@gmail.comwrote: 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
Re: [rust-dev] Rust docs
do you have a buildbot or jenkins for the rust ? I don't think travis could push html pages to a remote repository, do it? - Gaetan 2013/11/14 Benjamin Striegel ben.strie...@gmail.com 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 ___ Rust-dev mailing list Rust-dev@mozilla.org https://mail.mozilla.org/listinfo/rust-dev
Re: [rust-dev] Rust docs
good :) so, what is missing to have an automatic generation of html page from a github page? - Gaetan 2013/11/14 Corey Richardson co...@octayn.net Travis could, but then anyone could (since the travis.yml is public and it'd need credentials to the repo). We have a buildbot, buildbot.rust-lang.org On Thu, Nov 14, 2013 at 12:39 PM, Gaetan gae...@xeberon.net wrote: do you have a buildbot or jenkins for the rust ? I don't think travis could push html pages to a remote repository, do it? - Gaetan 2013/11/14 Benjamin Striegel ben.strie...@gmail.com 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 ___ 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
Re: [rust-dev] Rust docs
We *do* do automatic generation. It uses the markdown in `doc`. tutorial.md, and rust.md is the manual. On Thu, Nov 14, 2013 at 12:51 PM, Gaetan gae...@xeberon.net wrote: good :) so, what is missing to have an automatic generation of html page from a github page? - Gaetan 2013/11/14 Corey Richardson co...@octayn.net Travis could, but then anyone could (since the travis.yml is public and it'd need credentials to the repo). We have a buildbot, buildbot.rust-lang.org On Thu, Nov 14, 2013 at 12:39 PM, Gaetan gae...@xeberon.net wrote: do you have a buildbot or jenkins for the rust ? I don't think travis could push html pages to a remote repository, do it? - Gaetan 2013/11/14 Benjamin Striegel ben.strie...@gmail.com 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 ___ 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
Re: [rust-dev] Rust docs
I completely share your views, Daniel. [Would have expressed them myself if I did not know (from experience) that constructive critics by me (in english) usually are mistaken or misunderstood: people just deny, argue, or reply violently. But you do a good job, here, in my opinion.] Denis On 11/14/2013 04:03 PM, Daniel Glazman wrote: Hello rust-dev, I would like to make a comment I feel is important about both the Rust tutorial and manual. Please don't misunderstand me, no flame here, I am sending this message to help. I think good docs are extremely important to increase the size of a community, and in particular make more people contribute to Servo (the reason why I'm here). If the Reference Manual for Rust tries to be complete and does not try to avoid language complexity, it can be from time to time hard to read because of one thing: examples are not well or often enough explained and are often too complex given the section they belong too. It's for instance difficult for the reader to understand an example of section n that uses notions explained only in section n+4. 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. Best regards, /Daniel ___ 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
Re: [rust-dev] Rust docs
Could there be a kind of rust-tutorial-in-progress wiki page? (with required subscription to edit). Seems to me the easiest path to cooperative edition. Then, just have a single person responsible for regularly pushing the 'in progress' version as the 'offical' one, whenever its state is ok. Denis ___ Rust-dev mailing list Rust-dev@mozilla.org https://mail.mozilla.org/listinfo/rust-dev
Re: [rust-dev] Rust docs
Honestly, I am not sure tutorial quality and automatic generation live well together. We hire tech evangelists for their ability to present well information and make messages percolate better, and similarly good doc requires good tech writers who only do that. As I said earlier, a tutorial is crucial material to attract people and I think writing talent, excellent presentation and correct readability are need for such a tutorial. When I say attract people or community, I am of course thinking of reaching critical masses for Rust-based projects, including Servo, and that requires making sure documentation material are good enough to self-generate a pool of potential hires. /Daniel ___ Rust-dev mailing list Rust-dev@mozilla.org https://mail.mozilla.org/listinfo/rust-dev
Re: [rust-dev] Rust docs
On 15/11/13 08:08, Daniel Glazman wrote: Honestly, I am not sure tutorial quality and automatic generation live well together. We hire tech evangelists for their ability to present well information and make messages percolate better, and similarly good doc requires good tech writers who only do that. As I said earlier, a tutorial is crucial material to attract people and I think writing talent, excellent presentation and correct readability are need for such a tutorial. When I say attract people or community, I am of course thinking of reaching critical masses for Rust-based projects, including Servo, and that requires making sure documentation material are good enough to self-generate a pool of potential hires. /Daniel ___ Rust-dev mailing list Rust-dev@mozilla.org https://mail.mozilla.org/listinfo/rust-dev Just for reference, the tutorial being suboptimal is a known bug: https://github.com/mozilla/rust/issues/9874 Huon ___ Rust-dev mailing list Rust-dev@mozilla.org https://mail.mozilla.org/listinfo/rust-dev
Re: [rust-dev] Rust docs
On 11/14/2013 07:03 AM, Daniel Glazman wrote: Hello rust-dev, 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 completely agree, and rewriting the tutorial specifically is the subject of #9874. We want to put a lot more effort into documentation for Rust 1.0 and are in fact actively looking for an amazing technical writer for this purpose. If anybody with a background in technical writing is passionate about this topic I'd love to hear from you privately. ___ Rust-dev mailing list Rust-dev@mozilla.org https://mail.mozilla.org/listinfo/rust-dev
