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. [a] https://trac.sagemath.org/query?order=status&desc=1&summary=~documentation&or&keywords=~documentation&or&component=documentation [b] https://wiki.sagemath.org/days77 > 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 https://github.com/sagemath/website/issues/86 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]. [1] https://www.google.com/search?q=sage+Elements+of+Quotients+of+Univariate+Polynomial+Rings [2] http://doc.sagemath.org/html/en/reference//polynomial_rings/sage/rings/polynomial/polynomial_quotient_ring_element.html [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: > 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. 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. [4] https://try.jupyter.org 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 https://trac.sagemath.org/ticket/21309 - #20690 Live documentation in Jupyter using Thebe https://trac.sagemath.org/ticket/20690 - #20893 Improve live documentation in the Jupyter notebook https://trac.sagemath.org/ticket/20893 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 -- 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 https://groups.google.com/group/sage-devel. For more options, visit https://groups.google.com/d/optout.
