Opened 5 years ago

Closed 5 years ago

#17255 closed enhancement (fixed)

Update developer and installation guide even more

Reported by: kcrisman Owned by:
Priority: major Milestone: sage-6.4
Component: documentation Keywords:
Cc: jdemeyer Merged in:
Authors: Karl-Dieter Crisman Reviewers: John Palmieri, Jeroen Demeyer
Report Upstream: N/A Work issues:
Branch: 08e1359 (Commits) Commit: 08e1359ff7798be94943f7c50ac44d0563e053e6
Dependencies: Stopgaps:

Description

#17112 was some needed reorganization of these resources. This ticket continues the process, especially by emphasizing direct steps for Mac. This was inspired by an email exchange with a nearly-thwarted would-be developer and the steps she took.

Change History (22)

comment:1 Changed 5 years ago by kcrisman

  • Dependencies set to #17112

comment:2 Changed 5 years ago by kcrisman

  • Authors set to Karl-Dieter Crisman
  • Status changed from new to needs_review

comment:3 follow-up: Changed 5 years ago by jdemeyer

Just a detail: it's Sage 6.4 now, not Sage 6.3

comment:4 in reply to: ↑ 3 Changed 5 years ago by kcrisman

Just a detail: it's Sage 6.4 now, not Sage 6.3

I thought about that for several minutes, actually, dithering on what to do. Because of course, in principle, there is no guarantee that this ticket will be reviewed and merged in Sage 6.4, or 6.5, or 7.0, or anything... so I went with the safest possible, which is that I wrote this during Sage 6.3.

But hopefully nearly trivial to change now that I'm more comfortable with git. Or you can do it as a reviewer patch if you do one :-)

comment:5 follow-up: Changed 5 years ago by jhpalmieri

On OS X, do you really need to register as a developer, or can you just download Xcode from the App Store and go from there?

comment:6 in reply to: ↑ 5 Changed 5 years ago by kcrisman

On OS X, do you really need to register as a developer, or can you just download Xcode from the App Store and go from there?

I don't know the answer to this question. They've changed their interface so much recently. But then at the very least you need to have an iTunes account, right? (And would they make you get a developer account to get Command Line Tools? I don't know that either.) That's why I don't use the App Store, though perhaps my developer account would work. If you can find out exact info on this it would be swell!

comment:7 Changed 5 years ago by kcrisman

Hmm, no longer applies.

comment:8 Changed 5 years ago by kcrisman

Okay, I think that this link and a few other comments online seem to confirm what John says. I've tried to update this appropriately.

If there is a quick review, then my change to 6.4 in the notes will still be accurate!

comment:9 Changed 5 years ago by kcrisman

  • Branch changed from u/kcrisman/develguideupdate to u/kcrisman/devguideup
  • Commit changed from 7a6e7c0f473d42ba13adb99eea88b30fa996587e to 61c551933b3e46529c10564a61e0298ac6772e06

New commits:

b9800ceUpdate/clarify prereqs for development
61c5519Reorganize and clarify Xcode download situation

comment:10 Changed 5 years ago by kcrisman

  • Dependencies #17112 deleted

comment:11 Changed 5 years ago by kcrisman

See also #17265, a followup.

comment:12 Changed 5 years ago by jdemeyer

  • Reviewers set to John Palmieri, Jeroen Demeyer

comment:13 follow-up: Changed 5 years ago by jdemeyer

Are links between manuals possible? Just asking because of

- Next, if you've never worked on software before, you will want to read
  about the `prerequisites to compile
  <http://www.sagemath.org/doc/installation/source.html#prerequisites>`_

which would ideally be an internal link.

comment:14 Changed 5 years ago by jdemeyer

  • Branch changed from u/kcrisman/devguideup to u/jdemeyer/ticket/17255
  • Created changed from 10/29/14 16:03:47 to 10/29/14 16:03:47
  • Modified changed from 10/31/14 10:46:46 to 10/31/14 10:46:46

comment:15 Changed 5 years ago by jdemeyer

  • Commit changed from 61c551933b3e46529c10564a61e0298ac6772e06 to baaedc9ecf9592ae77795feb64ed3230e2ec8038

I cannot judge the correctness of the OS X stuff, but apart from that the patch looks good. I'm adding a few small changes in this reviewer patch.


New commits:

baaedc9Small fixes to installation manual

comment:16 in reply to: ↑ 13 ; follow-up: Changed 5 years ago by kcrisman

Are links between manuals possible? Just asking because of... which would ideally be an internal link.

Yes, I totally agree, but I felt like it was only possible within sections of one manual, since each of them is built separately. (Otherwise, for instance, we could link to localizations of documents.)

The fixes are all good (I only focused on new updates, didn't think to update those things) except

-This section details the technical prerequisites needed on any platform. See
-`System-specific requirements`_ and `Installing prerequisites`_ for details
-on how to acquire these. :ref:`Mac OS X <section_macprereqs>` has
-special instructions as developer tools do not come standard.
+This section details the technical prerequisites needed on all platforms. See
+also the `System-specific requirements`_ below.

I purposely added all this originally because, in my experience with new developers that truly have no developing experience (and I do have a significant amount of experience with them), that little extra verbiage and especially the two additional links will make a big difference. The system requirements is not the same as actually installing them, and for many Mac users this is really foreign territory. Even if you insist on removing the Mac words, please do keep the installing prereqs link.

comment:17 in reply to: ↑ 16 ; follow-up: Changed 5 years ago by jdemeyer

Replying to kcrisman:

-This section details the technical prerequisites needed on any platform. See
-`System-specific requirements`_ and `Installing prerequisites`_ for details
-on how to acquire these. :ref:`Mac OS X <section_macprereqs>` has
-special instructions as developer tools do not come standard.
+This section details the technical prerequisites needed on all platforms. See
+also the `System-specific requirements`_ below.

I purposely added all this originally because, in my experience with new developers that truly have no developing experience (and I do have a significant amount of experience with them), that little extra verbiage and especially the two additional links will make a big difference.

On the other hand, too much text and superfluous references can also be confusing.

The system requirements is not the same as actually installing them, and for many Mac users this is really foreign territory.

In the guide, the sections "System-specific requirements" and "Installing prerequisites" are very close together, so a user clicking on "System-specific requirements" will see the "Installing prerequisites" section also. Moreover, "System-specific requirements" even has an explicit link for Mac OS X in the first sentence.

So I don't see what the problem could be with my changes.

comment:18 in reply to: ↑ 17 Changed 5 years ago by kcrisman

I purposely added all this originally because, in my experience with new developers that truly have no developing experience (and I do have a significant amount of experience with them), that little extra verbiage and especially the two additional links will make a big difference.

On the other hand, too much text and superfluous references can also be confusing.

Yes, I thought about this a fair amount. Unfortunately one doesn't have a focus group to test this on.

The system requirements is not the same as actually installing them, and for many Mac users this is really foreign territory.

In the guide, the sections "System-specific requirements" and "Installing prerequisites" are very close together, so a user clicking on "System-specific requirements" will see the "Installing prerequisites" section also. Moreover, "System-specific requirements" even has an explicit link for Mac OS X in the first sentence.

So I don't see what the problem could be with my changes.

The problem isn't your change, it's the huge amount of text below it. But I have come up with what I think will be a good compromise - one moment.

comment:19 Changed 5 years ago by kcrisman

  • Branch changed from u/jdemeyer/ticket/17255 to u/kcrisman/devguideup
  • Commit changed from baaedc9ecf9592ae77795feb64ed3230e2ec8038 to 08e1359ff7798be94943f7c50ac44d0563e053e6

New commits:

08e1359A little more structure to installation guide

comment:20 Changed 5 years ago by kcrisman

I couldn't figure out a way to get Sphinx to ignore two levels of headings after each other, which has some of the same "busy-ness" problems that you objected to.

Prerequisites General requirements

I tried to remove the words "General requirements" but got lots of errors; ReST is very strict about levels. I still think this is a better solution, hopefully you will agree.

comment:21 Changed 5 years ago by jdemeyer

  • Status changed from needs_review to positive_review

comment:22 Changed 5 years ago by vbraun

  • Branch changed from u/kcrisman/devguideup to 08e1359ff7798be94943f7c50ac44d0563e053e6
  • Resolution set to fixed
  • Status changed from positive_review to closed
Note: See TracTickets for help on using tickets.