Fwd: State of Sage Wiki and Support
68 views
Skip to first unread message
slelievre
Sep 9, 2016, 8:30:32 PM9/9/16
to Sage-devel
Le jeudi 1 septembre 2016 01:45:19 UTC+2, saad khalid a écrit :
Hey everyone:
It's seemed to me lately that the state of the documentation is kinda all over the place and dated. I've been having increasing trouble recently with finding the documentation for functions online, perhaps my Google skills are falling off? I know that you can always run function()? and have it give you the documentation, but I think it should be in a place were it's easy to find and read online. Mathematica's website has a great reference section for documenting its functions; it's informative and well presented. Ours, unfortunately, doesn't seem to be in one place. Also, both the function documentation and the main tutorial look quite dated. A while back I had sent in some feedback regarding Sage and what I thought needed improvement, and in that feedback I mentioned two websites whose layout looked very elegant. One of them is here:
https://www.atlassian.com/git/tutorials/
The other is this:
http://jupyter-notebook-beginner-guide.readthedocs.io/en/latest/execute.html
While their documentation might not be as thorough as ours is(at least, from what I could tell), I think the design and layout of their documentation is very very nice. I don't know how Atlassian does its layout (if they designed it on their own or use a premade layout), however I believe Jupyter uses something called https://readthedocs.org/, which is free. I honestly think that we should move over to what Jupyter is using for their documentation, at least for the tutorial. Perhaps there is something better for the documentation of functions, maybe something similar to what mathematic has set up.
I also think its important that all of the documentation be hosted at the same place.
What do you guys think? Do you like the layouts in the links above? Do you have any other ideas? I'm happy to help with this transition, if we do decide to do it. I could go on about this but, basically, I like the format mahematica uses for documenting its functions, and I like the format Jupyter(and Atlassian) uses for their tutorial. I don't know if any progress was being made on these things but, if not, I wanted to bring some attention to it and start a discussion about it. Thanks for taking the time to read this!
Samuel Lelievre
Sep 9, 2016, 9:51:02 PM9/9/16
to sage-devel
Thu 2016-09-01 01:45:19 UTC+2, saad khalid wrote on sage-support:
> Hey everyone:
Hey! Thanks for raising these points. I thought this discussion could
get more contributions on sage-devel, so I moved it here.
All please reply only on sage-devel to keep the discussion in one place.
> It's seemed to me lately that the state of the documentation is kinda
> all over the place and dated.
I agree that SageMath's documentation needs tender loving care.
To be fair, many efforts are taken to improve its state. For instance,
- there are a number of trac tickets about documentation [a]
- documentation was one of the themes of Sage days 77 in Cernay [b]
although more on the technical side: improving Sphinx docbuilding.
To be sure, the discussion you are proposing about how discoverable
Sage's documentation is, and how it can be perceived overall, has merit.
We are time and again reminded of some faults through various channels.
> I've been having increasing trouble recently
> with finding the documentation for functions online, perhaps my Google
> skills are falling off?
Your Google skills are most likely not the matter here. It's more our
skills at getting Google to properly index our html documentation files
at doc.sagemath.org, after we moved documentation there from its former
location at www.sagemath.org/doc recently. This is discussed at
One thing is that most links from "outside pages" to Sage documentation
still point to urls at www.sagemath.org/doc where the documentation used
to live until recently. That likely does not help doc.sagemath.org
being well indexed by Google's search engine. Hopefully that should
improve with time and some efforts, and doc.sagemath.org links should
make their way back to the top results in Google websearch results.
A test case is the websearch [1] which one would expect to get you straight
to [2] but, as it is, I don't get [2] in the results pages, even if I restrict
the search to doc.sagemath.org and use quotes, as in [3].
[3] https://www.google.com/search?q=sage+"Elements+of+Quotients+of+Univariate+Polynomial+Rings"+site:doc.sagemath.org
> I know that you can always run function()? and
> have it give you the documentation, but I think it should be in a place
> where it's easy to find and read online. Mathematica's website has a great
> reference section for documenting its functions; it's informative and
> well presented. Ours, unfortunately, doesn't seem to be in one place.
> Also, both the function documentation and the main tutorial look quite
> dated. A while back I had sent in some feedback regarding Sage and what
> I thought needed improvement, and in that feedback I mentioned two
> websites whose layout looked very elegant. One of them is here:
> The other is this:
>
> While their documentation might not be as thorough as ours is (at least,
> from what I could tell), I think the design and layout of their
> documentation is very very nice. I don't know how Atlassian does its
> layout (if they designed it on their own or use a premade layout),
> however I believe Jupyter uses something called https://readthedocs.org/,
> which is free. I honestly think that we should move over to what Jupyter
> is using for their documentation, at least for the tutorial. Perhaps
> there is something better for the documentation of functions, maybe
> something similar to what mathematic has set up.
It's true that it wouldn't hurt to have a bunch of polished up-to-date
easily discoverable tutorials that you can try immediately without any
setup effort, either online (tmpnb, SageCell, SageMathCloud) or on one's
own Sage if already installed.
On the one side, documentation and tutorials like those you point to,
on the other hand, some equivalent of Try Jupyter [4] in terms of ease.
In a sense, between SageCell and SageMathCloud, we already have the
"other hand", but not quite intertwined enough with the first hand.
Some recent and ongoing work that should help towards that is the work
around packaging Thebe and using it to get us live documentation in
Jupyter notebook worksheets like we have in Sage notebook worksheets.
Two steps are already done (#21309, #20690), and follow-up improvements
are being worked on at #20893.
- #21309 Package Thebe
- #20690 Live documentation in Jupyter using Thebe
- #20893 Improve live documentation in the Jupyter notebook
That should make it easier to play with the tutorials and with the
documentation in general.
> I also think its important that all of the documentation be hosted at the
> same place.
> What do you guys think? Do you like the layouts in the links above? Do
> you have any other ideas? I'm happy to help with this transition, if we
> do decide to do it. I could go on about this but, basically, I like the
> format mahematica uses for documenting its functions, and I like the
> format Jupyter (and Atlassian) use for their tutorials. I don't know if
> any progress was being made on these things but, if not, I wanted to
> bring some attention to it and start a discussion about it. Thanks for
> taking the time to read this!
It's great first of all that you care and launched this discussion.
I like the question you asked and I can see some benefits that could
come out of this discussion.
Samuel
kcrisman
Sep 10, 2016, 9:55:00 PM9/10/16
to sage-devel
Two steps are already done (#21309, #20690), and follow-up improvementsare being worked on at #20893.- #21309 Package Thebe- #20690 Live documentation in Jupyter using Thebe- #20893 Improve live documentation in the Jupyter notebook
This is great news, I had no idea that live doc was now available in Jupyter! Great work.
Reply all
Reply to author
Forward
0 new messages