State of Sage Wiki and Support
52 views
Skip to first unread message
saad khalid
Aug 31, 2016, 7:45:19 PM8/31/16
to sage-support
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!
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!
saad khalid
Sep 9, 2016, 5:43:33 PM9/9/16
to sage-support
bump
Is there any interest in this?
Is there any interest in this?
slelievre
Sep 9, 2016, 8:34:53 PM9/9/16
to sage-support
Hey! Thanks for raising these questions.
This list is more for questions about Sage usage, so I forwarded
your question to sage-devel, a more natural place to discuss it.
For anybody interested, the discussion is at:
Best, Samuel
Reply all
Reply to author
Forward
0 new messages