Re: [sage-devel] taskforce: documentation

[Nicolas M. Thiery]

On Thu, Aug 28, 2014 at 07:05:10AM -0700, kcrisman wrote:
>Relevant comments.
>1) There are a number of scattered resources for getting to know Sage
>that are actually useful at the level that poster is talking about.
>San Diego State tutorials, the PREP tutorials - which I happen to think
>are quite good ;-) - and others.

Aren't the PREP tutorials all in the Thematic Tutorials document now?

Of course, there could be more there!

>But they are not easy to find on the site, and (perhaps more
>importantly) the "official" tutorial, which is possibly the worst
>way to introduce a non-programmer or non-mathematician to Sage,
>has pride of place despite having not been updated in years, to
>my knowledge.

+1

>3) The reference documentation is not *organized* in a way useful to
>beginners.
>  > I have some vague ideas how this could be done and I think
>  > it's actually not so complicated - technically. It's harder
>  > to get input from different areas and from those who already
>  > have experience in teaching Sage in order to produce
>  > something really useful.

Interested to know if #16256 goes in the right direction :-)


http://sage.math.washington.edu/home/nthiery/sage/src/doc/output/html/en/reference/combinat/index.html

Cheers,
Nicolas
--
Nicolas M. Thiéry "Isil" 
http://Nicolas.Thiery.name/

-- 
You received this message because you are subscribed to the Google Groups 
"sage-devel" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to sage-devel+unsubscr...@googlegroups.com.
To post to this group, send email to sage-devel@googlegroups.com.
Visit this group at http://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

Re: [sage-devel] taskforce: documentation

[kcrisman]

>
> > currently anyone working on improving it? I think the reference 
> > documentation is really good. But I can see a definite lack to make it 
> more 
> > accessible to new users. Why not starting another branch and collect 
> > functionalities in a new way? 
>

Relevant comments.

1) There are a number of scattered resources for getting to know Sage that 
are actually useful at the level that poster is talking about.  San Diego 
State tutorials, the PREP tutorials - which I happen to think are quite 
good ;-) - and others.  But they are not easy to find on the site, and 
(perhaps more importantly) the "official" tutorial, which is possibly the 
worst way to introduce a non-programmer or non-mathematician to Sage, has 
pride of place despite having not been updated in years, to my knowledge.

2) It's hard for new people to contribute tutorials.  I have a friend who 
has a couple worksheets she would like to contribute as 
documentation/tutorials for useful situations but had to have me help with 
using sws2rst and sphinx and other stuff and then actually submitting and 
getting an Apple ID to compile and ... it's a lot to ask, in some ways.   
And I've been too busy to look into it so far, and more to the point one 
shouldn't have to know someone who has done this stuff to make it happen.

3) The reference documentation is not *organized* in a way useful to 
beginners.  


 > I have some vague ideas how this could be done and I think it's actually 
not 

> > so complicated - technically. It's harder to get input from different 
> areas 
> > and from those who already have experience in teaching Sage in order to 
> > produce something really useful. 
>

Yes.  Finding people with enough time and energy for this is big.  Greg 
spent a lng time on his AMS book, and I'm sure could have been 
productively doing other things with that time :-)
 

> > The cornerstones should be, in my eyes, that it is packaged and built 
> along 
> > Sage, displayed in a modern web-browser, and all examples are doctested. 
> > 
> > -- H 
>
> Yes, that would be great.   As some inspiration, there is also Gregory 
> Bard's new book "Sage for Undergraduates": 
>
>http://www.gregorybard.com/SAGE.html 
>
> William 
>
>
I read the Craig Finch book this summer as well, and shared it with a few 
students at Sage Days 60, and it's actually a very helpful introduction. 
 Something along the lines of either of these books (or perhaps the French 
Sage math book) would be a really good starting point for our own 
documentation efforts.

+++

Just for reference, more activity from the FB discussion on this.  I'm not 
intending for anyone to respond, just to make it more visible.


   - Luiz Roberto Meier  The 
   question now isn't if Sage can compete or not with a given proprietary 
   software but the learning curve to it and the different 'grammars' that the 
   initial user face. As I had talked with the author of this original thread 
   the question isn't who wins in the sense of speed of processing 
   something, like, prime numbers check or generators of prime numbers in a 
   given range. I don't care if Sage or Maple will win 2 seconds fastest than 
   Mathematica or any other mathematical software.
   
   Also, we must focus at least in three things:
   
   1) Sage should be used by students up to mathematicians with the Fields 
   Medal? If the answer is yes, good, let's do better manuals and mainly: 
   INTERFACE. By interface I means exactly what Mathematica does in the 
   software and in Wolfram Alpha. No matter what field of mathematics you are 
   dealing -- Mathematica always suggest things and are ready to plot it in 2D 
   or 3D as suggestion. This is handy for 'professionals' and for amateur in 
   any science field.
   
   2) 2D and 3D plots should run in any OS nowadays. jmol isn't good 
   anymore for that. Come on, we are in 8/2014. There is a lot of tools ready 
   to be used for that and I sugere the obvious: java or openjdk directly, 
   without the jmol trying to call it. (yes, I coded for the ProteinExplorer 
   site , long history)
   
   3) In the email cited the author says that don't matter if 100.000 
   people will use it or 100.000.000. Wrong. Sage is Open Source, it is free, 
   and it isn't an excuse to not write good code and mainly, organize it all. 
   In the contacts link of Sagemath site there is a word very important 
   called: DONATIONS. If money isn't important, tell me where you live , I 
   will be happy to live there too. Sage should be keep free and it isn't 
   wrong to receive donations and for that we need more USERS with all level 
   of knowledge in Mathematics or any other science. Donations help, for 
   example, Wikipedia to work. To pay for the hardware and the time of the 
   small staff. *I* do prefer to pay $5000 to a package that works for me and 
   my family than to donate to a place where I wish to help (coding and wit

Re: [sage-devel] taskforce: documentation

[William A Stein]

On Wed, Aug 27, 2014 at 7:15 PM, Harald Schilly
 wrote:
> I've read most of the comments which did roll in in the last few days. One
> repeated topic was about the documentation. I'm curious if there is
> currently anyone working on improving it? I think the reference
> documentation is really good. But I can see a definite lack to make it more
> accessible to new users. Why not starting another branch and collect
> functionalities in a new way?
> I have some vague ideas how this could be done and I think it's actually not
> so complicated - technically. It's harder to get input from different areas
> and from those who already have experience in teaching Sage in order to
> produce something really useful.
> The cornerstones should be, in my eyes, that it is packaged and built along
> Sage, displayed in a modern web-browser, and all examples are doctested.
>
> -- H

Yes, that would be great.   As some inspiration, there is also Gregory
Bard's new book "Sage for Undergraduates":

   http://www.gregorybard.com/SAGE.html

William

>
> --
> You received this message because you are subscribed to the Google Groups
> "sage-devel" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to sage-devel+unsubscr...@googlegroups.com.
> To post to this group, send email to sage-devel@googlegroups.com.
> Visit this group at http://groups.google.com/group/sage-devel.
> For more options, visit https://groups.google.com/d/optout.



-- 
William Stein
Professor of Mathematics
University of Washington
http://wstein.org
wst...@uw.edu

-- 
You received this message because you are subscribed to the Google Groups 
"sage-devel" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to sage-devel+unsubscr...@googlegroups.com.
To post to this group, send email to sage-devel@googlegroups.com.
Visit this group at http://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

[sage-devel] taskforce: documentation

[Harald Schilly]

I've read most of the comments which did roll in in the last few days. One 
repeated topic was about the documentation. I'm curious if there is 
currently anyone working on improving it? I think the reference 
documentation is really good. But I can see a definite lack to make it more 
accessible to new users. Why not starting another branch and collect 
functionalities in a new way?
I have some vague ideas how this could be done and I think it's actually 
not so complicated - technically. It's harder to get input from different 
areas and from those who already have experience in teaching Sage in order 
to produce something really useful. 
The cornerstones should be, in my eyes, that it is packaged and built along 
Sage, displayed in a modern web-browser, and all examples are doctested.

-- H

-- 
You received this message because you are subscribed to the Google Groups 
"sage-devel" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to sage-devel+unsubscr...@googlegroups.com.
To post to this group, send email to sage-devel@googlegroups.com.
Visit this group at http://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.