Opened 7 years ago

Closed 6 years ago

#16412 closed defect (fixed)

Update Sage FAQ

Reported by: knsam Owned by:
Priority: major Milestone: sage-6.5
Component: documentation Keywords:
Cc: was, SimonKing, leif, mvngu Merged in:
Authors: Frédéric Chapoton, Karl-Dieter Crisman Reviewers: Karl-Dieter Crisman, Frédéric Chapoton, Nathann Cohen
Report Upstream: N/A Work issues:
Branch: 6027377 (Commits, GitHub, GitLab) Commit: 6027377cb1377db84c82042d605f754258f79598
Dependencies: Stopgaps:

Status badges

Description

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

Change History (26)

comment:1 Changed 7 years ago by was

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.

comment:2 follow-up: Changed 7 years ago by kcrisman

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?

comment:3 Changed 7 years ago by leif

  • Cc leif added

comment:4 in reply to: ↑ 2 Changed 7 years ago by leif

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)

comment:5 follow-up: Changed 7 years ago by knsam

  • Cc mvngu added
  • Status changed from new to needs_info

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:

  1. 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...
  1. Isn't the list which answers the question "Who uses Sage" definitely obsolete?
  1. 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. 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:
  • 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).
  1. The question about jsMath is obsolete and must be removed.
  1. 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...]
  1. 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...

comment:6 in reply to: ↑ 5 Changed 7 years ago by was

Replying to knsam:

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

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

  1. 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.

  1. 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:

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).
  1. The question about jsMath is obsolete and must be removed.

Yes, totally obsolete.

  1. 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.

  1. 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...

comment:7 follow-up: Changed 7 years ago by leif

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).

comment:8 in reply to: ↑ 7 ; follow-up: Changed 7 years ago by knsam

Replying to leif:

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.

comment:9 in reply to: ↑ 8 Changed 7 years ago by leif

Replying to knsam:

Replying to leif:

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.)

comment:10 Changed 7 years ago by chapoton

  • Branch set to public/ticket/16412
  • Commit set to 747cf41047c047e95e537ad30fdbe1abd8073a30

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

Please review #16104 first !


New commits:

747cf41trac #16412 refactoring the faq

comment:11 Changed 7 years ago by vbraun_spam

  • Milestone changed from sage-6.3 to sage-6.4

comment:12 Changed 7 years ago by jdemeyer

Any reason why this is not needs_review?

comment:13 Changed 7 years ago by chapoton

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

comment:14 Changed 6 years ago by kcrisman

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

comment:15 Changed 6 years ago by kcrisman

  • Status changed from needs_info to needs_work

comment:16 Changed 6 years ago by kcrisman

  • Branch changed from public/ticket/16412 to u/kcrisman/ticket/16412
  • Commit changed from 747cf41047c047e95e537ad30fdbe1abd8073a30 to 330915f59af659b9b8a0a384b9f8a6a75214f82e

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:

330915ftrac #16412 refactoring the faq

comment:17 Changed 6 years ago by kcrisman

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

comment:18 Changed 6 years ago by kcrisman

  • Authors set to Frédéric Chapoton, Karl-Dieter Crisman
  • Reviewers set to Karl-Dieter Crisman
  • Status changed from needs_work to needs_review

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

comment:19 Changed 6 years ago by git

  • Commit changed from 330915f59af659b9b8a0a384b9f8a6a75214f82e to 7679633493e48e68d4631b27536ba84b920f4f99

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

7679633More improvements to FAQ

comment:20 Changed 6 years ago by ncohen

  • Branch changed from u/kcrisman/ticket/16412 to public/16412
  • Commit changed from 7679633493e48e68d4631b27536ba84b920f4f99 to 9f2ecde3636dcdfed6bdb637304cb57e8d54517c

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:

1) 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)

2) 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:

ff932a7trac #16412: Merged with 6.5.beta4
9f2ecdetrac #16412: Review

comment:21 Changed 6 years ago by chapoton

  • Reviewers changed from Karl-Dieter Crisman to Karl-Dieter Crisman, Frédéric Chapoton, Nathann Cohen
  • Status changed from needs_review to positive_review

Ok, looks good to me.

comment:22 Changed 6 years ago by chapoton

  • Milestone changed from sage-6.4 to sage-6.5

comment:23 Changed 6 years ago by vbraun

  • Status changed from positive_review to needs_work

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

comment:24 Changed 6 years ago by git

  • Commit changed from 9f2ecde3636dcdfed6bdb637304cb57e8d54517c to 6027377cb1377db84c82042d605f754258f79598

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

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

comment:25 Changed 6 years ago by ncohen

  • Status changed from needs_work to positive_review

Sorry for that.

Nathann

comment:26 Changed 6 years ago by vbraun

  • Branch changed from public/16412 to 6027377cb1377db84c82042d605f754258f79598
  • Resolution set to fixed
  • Status changed from positive_review to closed
Note: See TracTickets for help on using tickets.