Opened 4 years ago

Closed 4 years ago

#18405 closed enhancement (fixed)

Cleanup in the 'installation' manual

Reported by: ncohen Owned by:
Priority: major Milestone: sage-6.8
Component: documentation Keywords:
Cc: chapoton, mmezzarobba, kcrisman, jdemeyer, tmonteil, vdelecroix Merged in:
Authors: Nathann Cohen Reviewers: Jeroen Demeyer
Report Upstream: N/A Work issues:
Branch: 0d2ed87 (Commits) Commit: 0d2ed87f5f5f19f01032804c5278a11368518720
Dependencies: Stopgaps:

Description (last modified by ncohen)

The installation manual is the first thing I get when I type 'install Sage' in Google. And from that manual, it is not totally obvious how Sage should be installed (especially from its sources). Read it and see how hard it is to get the basic info, like 'what to download' and 'what to type'

This branch tries to clean that manual a bit, mostly by moving things around, making lengthy explanations shorter and adding table of contents where one is needed.

In particular:

  • There is no need of a section about how to build the doc in this manual. It is already explained somewhere else (in the developer's manual), and the doc is already built when you install Sage anyway.
  • The section on SageTex? is being moved to the (already existing) tutorial/sagetex document. Indeed:
    • Something as specific as 'how to configure Sagetex' does not belong to a document explaining how Sage should be installed (many packages require specific configuration, e.g. CPLEX,Gurobi,dot2tex,...)
    • Many links from the SageTex? tutorial are broken if no internet connection is available, as they point directly to the online 'installation' manual. Besides, they point to the index and not to the actual install page. http://www.sagemath.org/doc/tutorial/sagetex.html
    • Some information is repeated in both documents (which usually leads to only one of the two being updated)
  • 'Desktop icon' is renamed to 'KDE Desktop icon'. Though I do not personally believe that it is Sage's role to explain how to customize KDE.

Further work will have to be done to clean&simplify the two pages: http://www.sagemath.org/doc/installation/source.html http://www.sagemath.org/doc/installation/binary.html

Nathann

Change History (7)

comment:1 Changed 4 years ago by ncohen

  • Branch set to public/18405
  • Commit set to dbd2c63637a6d6d71eec606959b85931295dc973
  • Description modified (diff)
  • Status changed from new to needs_review

New commits:

006c90ftrac #18405: Shorten the index page
b276bf8trac #18405: Explaining how to build the doc is already done somewhere else
4104795trac #18405: 'Desktop icon' -> 'KDE Desktop icon'
bd702c0trac #18405: *move* the content of sagetex.rst to the sagetex tutorial (nothing else is done)
844361dtrac #18405: Merge the two documents and remove the old index entry
b6836c6trac #18405: Move the first paragraph of the intro to the index
b25b0c9trac #18405: Rename 'introduction' to 'standard_packages'
1e1f25atrac #18405: Simplify the first paragraph of 'index'
dbd2c63trac #18405: Links and typoes

comment:2 follow-up: Changed 4 years ago by kcrisman

I like the overall idea behind this ticket, but I think you should separate this into "cleaning up things that truly are a mess" and "removing/moving large sections that may or may not belong in the installation guide". Among other things, this may break third-party links... but mostly I think that I would like to expand the influence of the installation guide and make it more obvious, not make it harder to find things. So the more extra information (KDE, SageTeX, ...) the merrier! As long as it's well organized. And certainly those things fall under "installation"; I would be happy to include information about CPLEX and friends there, as a one-stop-shop is a good thing. Then the tutorial could point to the installation guide for installation questions, leaving the tutorial to be just a tutorial.

I'll try to look at this next week in more detail, in any case, thanks for starting this process!

comment:3 in reply to: ↑ 2 Changed 4 years ago by ncohen

Yo !

I like the overall idea behind this ticket, but I think you should separate this into "cleaning up things that truly are a mess" and "removing/moving large sections that may or may not belong in the installation guide".

To be honest this branch does not 'clean up' a lot of mess. That was my first intent, but I figured out that it would be too much for one ticket, so I left it out. Except for a couple of typoes, this branch only moves things around: much more work will have to go into the 'install from sources' and 'install from binaries' pages, in other tickets.

Among other things, this may break third-party links...

I understand, though that should not stop us from reorganizing our doc. If you want some kind of 'deprecation' for the doc we could add empty pages (corresponding to the ones I removed), saying that the doc is now available somewhere else.

I do not mind doing that if you ask, but if you do please create a poll on sage-devel to ask what everybody thinks. That would be some kind of 'deprecation policy' for doc.

but mostly I think that I would like to expand the influence of the installation guide and make it more obvious, not make it harder to find things. So the more extra information (KDE, SageTeX, ...) the merrier! As long as it's well organized. And certainly those things fall under "installation"; I would be happy to include information about CPLEX and friends there, as a one-stop-shop is a good thing. Then the tutorial could point to the installation guide for installation questions, leaving the tutorial to be just a tutorial.

While we should obviously provide as ample and useful explanations as possible with respect to all packages that we provide (even the optional ones), I think that gathering them all in this document would be a mistake.

Each package would have pretty different instructions, and nobody would be interested by the 'installation instructions for all "complicated" packages". We should make this information available, but we should keep it close to the general documentation on these packages. It would give us, for each package, a self-contained page about its uses and its installation instruction, if necessary.

Furthermore, there does not seem to be a reliable way to link *between* documents (except toward the reference manual). If we had all installation instructions in this 'installation' manual, we would not be able to link from a tutorial to the installation instructions (this branch actually removes some such links), or from the installation back to the tutorial.

Also, I know for a fact that I only update reliably the files on which I work. I forgot one thousand times to update the MILP tutorial when I update the code, and I know that this would not happen if everything was in the same file (as I browse its code and documentation much more often). On the other hand, anybody working on a manual would necessarily recompile it often, glance at it and notice some other thing which should be updated too.

I am in favor of pages explaining at the same time how the software can be used, and how it should be installed. Of course, we have ReST chapter to differenciate the two in the same page.

Nathann

comment:4 Changed 4 years ago by jdemeyer

  • Milestone changed from sage-6.7 to sage-6.8
  • Reviewers set to Jeroen Demeyer
  • Status changed from needs_review to needs_work

I agree with everything except for

 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1

If you undo this change, you can set this to positive_review.

comment:5 Changed 4 years ago by git

  • Commit changed from dbd2c63637a6d6d71eec606959b85931295dc973 to 0d2ed87f5f5f19f01032804c5278a11368518720

Branch pushed to git repo; I updated commit sha1. New commits:

c521231trac #18405: Merged with 6.8.beta7
0d2ed87trac #18405: Reviewer's comment

comment:6 Changed 4 years ago by ncohen

  • Status changed from needs_work to positive_review

Thank you!

Nathann

comment:7 Changed 4 years ago by vbraun

  • Branch changed from public/18405 to 0d2ed87f5f5f19f01032804c5278a11368518720
  • Resolution set to fixed
  • Status changed from positive_review to closed
Note: See TracTickets for help on using tickets.