> Exactly. I wouldn't like to have documentation that is *not* included in the > SageMath sources. Currently, one can access all documentation locally, during > a > SageMath session.
+1 Most of the Feature Tour pages http://www.sagemath.org/tour.html are not in the source tree. They are also somewhat out of date, especially Benchmarks (comparing SageMath 4.1.1 with Mathematica 7). That page links to "A Guided tour of Sage" in the compiled doc (http://doc.sagemath.org/html/en/tutorial/tour.html), which is something different than "A tour of Sage" (http://doc.sagemath.org/html/en/a_tour_of_sage/index.html). Three different places to have a "tour" -- horrendous! Under the Documentation main page doc.sagemath.org, the "guided tour" is called "tutorial". And it is listed after "Thematic Tutorial" though it should surely be visited first by a newcomer. > On the "help/documentation" page, I'd prefer a list of the available documents > and for each item on the list a drop-down menue for choosing one's language. > And > please not a bunch of links named "Ref: Probability Ref: Quadratic Forms etc" > on that page. Instead, there could be a link "Chapters" that leads to a table > of > contents. +1 In general, we have so many lists of documents that you can read that it's total information overload, and the user is confused on even where to start. Compare e.g. http://www.sagemath.org/help.html http://www.sagemath.org/tour.html http://www.sagemath.org/library.html http://doc.sagemath.org/ http://doc.sagemath.org/html/en/ I know they're all different and serve different purposes etc., but it's not very helpful for a new user. If the documentation is structured in a simple, immediately logical fashion, it's easier for users to know where to seek further help. And we should make absolutely guaranteed sure that every user gets to know about tab-completion and ?-help. These two tricks make Sage so much easier and more fun to learn! > So, perhaps/probably it is possible to improve sagemath.org. E.g., I find the > front page ok. Compared with modern open source project web pages, I find it noisy and somewhat unprofessional. There's 7-9 menus of links, depending on how you count, with even more links scattered outside this. For instance, the ugly "Do you want to learn how to use SageMath"-box currently adorning the page has no place there. It's also boring and uninspiring. We should get a beautiful, colourful design with banner images of some cool plots and some rendered latex equations, and with some 1-2 sentence taglines. And then the main buttons "Try Online", "Download", "Documentation", and "Development". At the top, a single menu with items like our main menu now. Just thinking out loud... Best, Johan Simon King writes: > Hi! > > On 2017-02-06, Clemens Heuberger <clemens.heuber...@aau.at> wrote: >> Am 2017-02-05 um 03:22 schrieb kcrisman: >>> >>> "Tutorial", "Thematic Tutorial", "PREP Tutorial", "A Tour of Sage". and >>> "Constructions" are mostly the same Tutorial. >>> >>> >>> Just for clarification, these are massively and completely different >>> documents. >>> There is also a lot of overlap, but the audiences are very different. The >>> challenge is getting the right people to the right tutorial/introduction, or >>> perhaps writing new ones and making them easy to find. ... >> one more point: as part of the sage source tree, these tutorials are tested >> regularly and so it is guaranteed that they work with the most recent sage >> version. > > Exactly. I wouldn't like to have documentation that is *not* included in the > SageMath sources. Currently, one can access all documentation locally, during > a > SageMath session. > > Usually I find it very very easy to search for relevant documentation in > SageMath - say, by search_def or search_src or by ? or ?? or tab completion. > Actually I believe that the documentation is a strength of SageMath. > > However, the paragraph above indicates a problem: Before being able to enjoy > the > good SageMath documentation, one needs to learn how to access stuff. For > newbies, it might be problematic to some extent. But this problem cannot be > solved by removing the above tools. Instead, newbies should be pointed to > using > them. > > So, perhaps/probably it is possible to improve sagemath.org. E.g., I find the > front page ok, but I find both the download page and the page > "help/documentation" confusing: Both consist of very long lists of links > (e.g., to download servers or to separate chapters of the PDF documentation or > different languages). > > On the "help/documentation" page, I'd prefer a list of the available documents > and for each item on the list a drop-down menue for choosing one's language. > And > please not a bunch of links named "Ref: Probability Ref: Quadratic Forms etc" > on that page. Instead, there could be a link "Chapters" that leads to a table > of > contents. > > Best regards, > Simon -- -- 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.
