> What is the argument for removing the tour? I have seen absolutely no
> arguments at for removing it, except maybe "the first section of that
manual
> is also named "A guided tour".' That's not a compelling argument. A
> piece of our documentation has a target audience (or audience) and a goal
> about what it should accomplish for them. The tour presumably has as a
> target audience people who want to learn something about sage, probably
> interactively, in about 10 minutes. And it's aimed at people who have
> never used Sage before.
Please William, do not be so defensive.
I am not your enemy, I am not Sage's enemy, and I spent my whole
week-end writing doc patches [1]. I only want to improve our
documentation, for all users.
Here is the reason why I believe that this document is not
something we want to show to the users [2]
- It is entitled "A tour of Sage", and it does not (at all) give
an overview of what Sage does (and makes it a perfect tool in
some fields)
- It only shows basic things that you can do with one thousand
other softwares
- It looks unfinished: look at the bottom of the page. Please
look at it.
Here is why I think that it is advertised at the wrong place:
- It appears at the root of all our documentation [3], on the
same level as the developer's manual, the reference manual, or
the actual 'tutorial' (thematic or not)
- If you do not know better, you could honestly believe that this
'Tour of Sage' is the only documentation we have for very very
new users
Why I think that we should remove it:
- You witnessed that plenty of our documentation is outdated. We
cannot keep and maintain all this doc. We need to have fewer
documents, we cannot do it otherwise.
- We cannot make a document update itself, and we cannot order
anybody to do it. If we keep it, it will stay as it is for a
long time (since Mike Hansen wrote it in 2009, only broken
doctests have been changed).
If you refuse to see it removed [4], I believe that it should be
turned into a sub-document of the tutorial. Under a different
name. Something like 'A 5-minutes overview of Sage'.
I honestly believe that it would be a pity to not remove it. Some
short document, at this entry level, is indeed needed but this
page alone is bad work. Let us remove it, and re-do it from
scratch later. This document does not help us: in its current
state, new users should rather consult the 'tutorial'
document (and its table of contents, for a quick overview).
Nathann
P.S.: I need help to review the trac tickets from [1]. This is
only documentation to review, it is easy, but I need those
ticket to be reviewed before I can write more.
[1]
http://trac.sagemath.org/query?status=needs_review&component=documentation&col=id&col=summary&col=status&col=type&col=priority&col=milestone&col=component&order=priority
[2] http://www.sagemath.org/doc/a_tour_of_sage/index.html
[3] http://www.sagemath.org/doc/index.html
[4] I am powerless against that. The same way that in the review
process the reviewer is all-powerful, and the author can only
obey if he wants his patch to pass.
--
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 http://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.
