Update Sage FAQ #16412

KPanComputes · 2014-05-30T01:03:59Z

As pointed out by William on this sage-support thread.

SAGE FAQ must be updated; here is what it looks like now:

http://sagemath.org/doc/faq/index.html

CC: @williamstein @simon-king-jena @nexttime @sagetrac-mvngu

Component: documentation

Author: Frédéric Chapoton, Karl-Dieter Crisman

Branch/Commit: 6027377

Reviewer: Karl-Dieter Crisman, Frédéric Chapoton, Nathann Cohen

Issue created by migration from https://trac.sagemath.org/ticket/16412

The text was updated successfully, but these errors were encountered:

williamstein · 2014-05-30T01:20:49Z

comment:1

And we should update how we host the faq. Maybe put it in the sage source code? Maybe move it to wiki.sagemath.org? I don't know.

kcrisman · 2014-05-30T02:13:18Z

comment:2

If I'm not mistaken, it is in the source already.

$ ls src/doc/en/faq
conf.py			faq-usage.rst		templates
faq-contribute.rst	index.rst
faq-general.rst		static

Or did I misunderstand this question?

nexttime · 2014-05-30T13:47:57Z

comment:4

Replying to @kcrisman:

If I'm not mistaken, it is in the source already.

Yes, and it even occasionally gets updated... :-) (see e.g. #15307)

KPanComputes · 2014-05-31T18:19:58Z

comment:5

Hi,

I am going to be unable to submit this (or any) patch for atleast two weeks from now as my Mac cannot connect to a non-wireless internet ATM. But, there are a couple of points that need to be discussed; please also point me to more up-to-date information and if possible, adding to pointers to potential addition would help me:

It says the FAQ is maintained by Minh Van Nguyen. So, I am ccing him on this ticket and I hope he does not mind...
Isn't the list which answers the question "Who uses Sage" definitely obsolete?
In the question about getting help, we should probably add http://ask.sagemath.org. I think it could be helpful if we could somehow get a Stack Exchange Site for Sage. But this might be easy or hard depending upon the initial momentum. I could try submitting an initial proposal on Area 51 but we need a huge lot of support in the beginning to get started. But once done, I think we can keep the momentum going...
The answer to the question "How do I get started?" mentions sagenb.org. But I have been under the impression that support might be dropped for sagenb. Is this not so? Also, some subremarks/subquestions:
- Should we mention http://cloud.sagemath.org here? (And, of course update the rest of the text...)
- Sage Cell Servers should be surely mentioned.
- The bit of the answer about Sage Notebook on a non-default browser is probably out of place and is slightly confusing (opera should be replaced by sth generic: <browser-name> or such).
The question about jsMath is obsolete and must be removed.
We should go through mailing list and get a list of things that people often ask or mistakenly assume and notice odd behaviour. Some that come to mind:

Polynomials vs Symbolic Expressions
Writing a given integer in different basis.
IPython Terminal Colour and other stuff
[etc...]

The section "Contributing to Sage" needs to mention GIT, the new GIT Trac and probably some more questions that one has about developing with GIT. I have had a lot of these questions recently and could probably contribute a couple of questions here.

This section could advertise an invitation for people to contribute doctests: see #12891 for where this is coming from. :-)

OK, this is my preliminary set of observations. If there are more, please put them in a comment here...

williamstein · 2014-05-31T18:38:15Z

comment:6

Replying to @KPanComputes:

Isn't the list which answers the question "Who uses Sage" definitely obsolete?

Yes, and if not, it is likely to quickly become so...

In the question about getting help, we should probably add http://ask.sagemath.org. I think it could be helpful if we could somehow get a Stack Exchange Site for Sage. But this might be easy or hard depending upon the initial momentum. I could try submitting an initial proposal on Area 51 but we need a huge lot of support in the beginning to get started. But once done, I think we can keep the momentum going...

+1. We could write to sage-devel and ask people to vote for it.

The answer to the question "How do I get started?" mentions sagenb.org. But I have been under the impression that support might be dropped for sagenb. Is this not so?

The website http://sagenb.org will cease to exist, though the timeframe is unclear.

Also, some subremarks/subquestions:

Should we mention http://cloud.sagemath.org here? (And, of course update the rest of the text...)

Yes. I bet a significant fraction of new people who use Sage use it through http://cloud.sagemath.org

 - Sage Cell Servers should be surely mentioned. 

 - The bit of the answer about Sage Notebook on a non-default browser is probably out of place and is slightly confusing (`opera` should be replaced by sth generic: `<browser-name>` or such).

The question about jsMath is obsolete and must be removed.

Yes, totally obsolete.

We should go through mailing list and get a list of things that people often ask or mistakenly assume and notice odd behaviour. Some that come to mind:

Polynomials vs Symbolic Expressions

Writing a given integer in different basis.

IPython Terminal Colour and other stuff

[etc...]

It would also be better if people could easily add to the FAQ when they answer such questions. The whole trac-based dev process is too cumbersome for quick FAQ entries.

The section "Contributing to Sage" needs to mention GIT, the new GIT Trac and probably some more questions that one has about developing with GIT. I have had a lot of these questions recently and could probably contribute a couple of questions here.

This section could advertise an invitation for people to contribute doctests: see #12891 for where this is coming from. :-)

OK, this is my preliminary set of observations. If there are more, please put them in a comment here...

nexttime · 2014-05-31T19:06:32Z

comment:7

I think continually trying to replicate what is (mostly already) answered elsewhere is doomed to fail (or to again become obsolete soon), so we should probably concentrate on very basic questions and answers [that aren't likely to change soon] (although a lot probably also belongs to the README) and just provide links to other resources (and specific answers).

KPanComputes · 2014-05-31T19:13:42Z

comment:8

Replying to @nexttime:

Is your last comment in reference to my point (6)? If so, do you mean that we should not have anything about common mistakes that people make when coming to Sage anew? For example, the polynomial vs symbolic expression has appeared on sage-support quite often!

While I agree with you that we should not add stuff that we should not add things that would become obsolete quickly, I guess some of these points appear so often that it is probably worth having some standard answers to refer people to. Do you agree here?

-- Kannappan.

nexttime · 2014-05-31T19:34:58Z

comment:9

Replying to @KPanComputes:

Replying to @nexttime:

Is your last comment in reference to my point (6)? If so, do you mean that we should not have anything about common mistakes that people make when coming to Sage anew? For example, the polynomial vs symbolic expression has appeared on sage-support quite often!

While I agree with you that we should not add stuff that we should not add things that would become obsolete quickly, I guess some of these points appear so often that it is probably worth having some standard answers to refer people to. Do you agree here?

Well, IMHO the main problem currently is that we have an unordered list of random topics.

I'd actually ask on sage-support etc. what users think should be answered / are the common problems and pitfalls (installing Sage / using Sage / using this and that). (This could be done regularly, and we could also post an updated [short] FAQ monthly, say.)

There are also frequently general questions regarding the relationsship of Sage's Python and packages to system ones. (Or in other words, a couple of specific questions arise because users don't know enough about how Sage is designed / structured.)

fchapoton · 2014-07-26T12:40:05Z

Commit: 747cf41

fchapoton · 2014-07-26T12:40:05Z

Branch: public/ticket/16412

fchapoton · 2014-07-26T12:40:05Z

comment:10

Here is a git branch with a few changes, still needs works of course.

Please review #16104 first !

New commits:

`747cf41`	`trac #16412 refactoring the faq`

jdemeyer · 2014-08-31T08:02:11Z

comment:12

Any reason why this is not needs_review?

fchapoton · 2014-08-31T10:02:28Z

comment:13

Well, I would say this is only a first step. But of course, it is better than doing nothing.

kcrisman · 2014-12-15T19:15:27Z

comment:14

Needs rebase - if I get time today I'll do it, even. But see also #16628 and #17491 for possible further work.

kcrisman · 2014-12-15T20:25:34Z

Changed commit from 747cf41 to 330915f

kcrisman · 2014-12-15T20:25:34Z

Changed branch from public/ticket/16412 to u/kcrisman/ticket/16412

kcrisman · 2014-12-15T20:25:34Z

comment:16

Sorry for moving this off the public ticket, I wasn't sure how to do that right. In any case I kept the author.

New commits:

`330915f`	`trac #16412 refactoring the faq`

kcrisman · 2014-12-15T20:36:09Z

comment:17

I'll momentarily take care of a few of these other issues on this ticket.

kcrisman · 2014-12-15T21:03:01Z

Author: Frédéric Chapoton, Karl-Dieter Crisman

kcrisman · 2014-12-15T21:03:01Z

comment:18

Okay, this should be ready for review. I'm happy with chapoton's changes, fwiw.

Yet to do:

Adding more actual frequently asked questions
Organizing in a sane way
updated developer info more

kcrisman · 2014-12-15T21:03:01Z

Reviewer: Karl-Dieter Crisman

sagetrac-git · 2014-12-15T21:03:35Z

Branch pushed to git repo; I updated commit sha1. New commits:

`7679633`	`More improvements to FAQ`

sagetrac-git · 2014-12-15T21:03:35Z

Changed commit from 330915f to 7679633

nathanncohen · 2014-12-31T10:36:02Z

comment:20

Hello guys !

I made a pass on this patch, and I do not have much to add. I actually changed the "How do I get started" section a bit, because:

The same instructions were repeated twice (sagecloud, sagenb, the binaries) and a sentence did not even end (a link toward the download page was missing)
It feels a bit weird to have the section "How do I get started" begin with an advertisement for the cloud. I did not remove anything, but only moved the Cloud+Sagenb+Sage cell into a list entitled "when you do not want to download anything".

Hoping that you will have no problem with this, I pused the changes to a new branch (and I updated the ticket). If you can review my commit, this branch can get it !

Nathann

New commits:

`ff932a7`	`trac #16412: Merged with 6.5.beta4`
`9f2ecde`	`trac #16412: Review`

nathanncohen · 2014-12-31T10:36:02Z

Changed branch from u/kcrisman/ticket/16412 to public/16412

nathanncohen · 2014-12-31T10:36:02Z

Changed commit from 7679633 to 9f2ecde

fchapoton · 2015-01-18T16:22:41Z

comment:21

Ok, looks good to me.

fchapoton · 2015-01-18T16:22:41Z

Changed reviewer from Karl-Dieter Crisman to Karl-Dieter Crisman, Frédéric Chapoton, Nathann Cohen

vbraun · 2015-01-23T16:46:27Z

comment:23

This is a doctest that attempts to launch a browser:

+You can also run it from the command line of sage::
+
+    sage: notebook()

Times out for me, though might also cause other undesirable behavior

sagetrac-git · 2015-01-23T16:49:01Z

Changed commit from 9f2ecde to 6027377

sagetrac-git · 2015-01-23T16:49:01Z

Branch pushed to git repo; I updated commit sha1. New commits:

`69f0f4c`	`trac #16412: Merged with 6.5.beta5`
`6027377`	`trac #16412: dangerous doctest`

nathanncohen · 2015-01-23T16:49:14Z

comment:25

Sorry for that.

Nathann

vbraun · 2015-01-24T13:19:14Z

Changed branch from public/16412 to 6027377

KPanComputes added this to the sage-6.3 milestone May 30, 2014

KPanComputes added c: documentation labels May 30, 2014

KPanComputes added the s: needs info label May 31, 2014

sagetrac-vbraun-spam mannequin modified the milestones: sage-6.3, sage-6.4 Aug 10, 2014

kcrisman added s: needs work and removed s: needs info labels Dec 15, 2014

kcrisman added s: needs review and removed s: needs work labels Dec 15, 2014

fchapoton added s: positive review and removed s: needs review labels Jan 18, 2015

fchapoton modified the milestones: sage-6.4, sage-6.5 Jan 23, 2015

vbraun added s: needs work and removed s: positive review labels Jan 23, 2015

nathanncohen mannequin added s: positive review and removed s: needs work labels Jan 23, 2015

vbraun removed the s: positive review label Jan 24, 2015

vbraun closed this as completed in 527c166 Jan 24, 2015

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update Sage FAQ #16412

Update Sage FAQ #16412

KPanComputes commented May 30, 2014

williamstein commented May 30, 2014

kcrisman commented May 30, 2014

nexttime mannequin commented May 30, 2014

KPanComputes commented May 31, 2014

williamstein commented May 31, 2014

nexttime mannequin commented May 31, 2014

KPanComputes commented May 31, 2014

nexttime mannequin commented May 31, 2014

fchapoton commented Jul 26, 2014

fchapoton commented Jul 26, 2014

fchapoton commented Jul 26, 2014

jdemeyer commented Aug 31, 2014

fchapoton commented Aug 31, 2014

kcrisman commented Dec 15, 2014

kcrisman commented Dec 15, 2014

kcrisman commented Dec 15, 2014

kcrisman commented Dec 15, 2014

kcrisman commented Dec 15, 2014

kcrisman commented Dec 15, 2014

kcrisman commented Dec 15, 2014

kcrisman commented Dec 15, 2014

sagetrac-git mannequin commented Dec 15, 2014

sagetrac-git mannequin commented Dec 15, 2014

nathanncohen mannequin commented Dec 31, 2014

nathanncohen mannequin commented Dec 31, 2014

nathanncohen mannequin commented Dec 31, 2014

fchapoton commented Jan 18, 2015

fchapoton commented Jan 18, 2015

vbraun commented Jan 23, 2015

sagetrac-git mannequin commented Jan 23, 2015

sagetrac-git mannequin commented Jan 23, 2015

nathanncohen mannequin commented Jan 23, 2015

vbraun commented Jan 24, 2015

Update Sage FAQ #16412

Update Sage FAQ #16412

Comments

KPanComputes commented May 30, 2014

williamstein commented May 30, 2014

kcrisman commented May 30, 2014

nexttime mannequin commented May 30, 2014

KPanComputes commented May 31, 2014

williamstein commented May 31, 2014

nexttime mannequin commented May 31, 2014

KPanComputes commented May 31, 2014

nexttime mannequin commented May 31, 2014

fchapoton commented Jul 26, 2014

fchapoton commented Jul 26, 2014

fchapoton commented Jul 26, 2014

jdemeyer commented Aug 31, 2014

fchapoton commented Aug 31, 2014

kcrisman commented Dec 15, 2014

kcrisman commented Dec 15, 2014

kcrisman commented Dec 15, 2014

kcrisman commented Dec 15, 2014

kcrisman commented Dec 15, 2014

kcrisman commented Dec 15, 2014

kcrisman commented Dec 15, 2014

kcrisman commented Dec 15, 2014

sagetrac-git mannequin commented Dec 15, 2014

sagetrac-git mannequin commented Dec 15, 2014

nathanncohen mannequin commented Dec 31, 2014

nathanncohen mannequin commented Dec 31, 2014

nathanncohen mannequin commented Dec 31, 2014

fchapoton commented Jan 18, 2015

fchapoton commented Jan 18, 2015

vbraun commented Jan 23, 2015

sagetrac-git mannequin commented Jan 23, 2015

sagetrac-git mannequin commented Jan 23, 2015

nathanncohen mannequin commented Jan 23, 2015

vbraun commented Jan 24, 2015