Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Move installation details from README to the installation guide #38659

Open
wants to merge 4 commits into
base: develop
Choose a base branch
from

Conversation

kwankyu
Copy link
Collaborator

@kwankyu kwankyu commented Sep 14, 2024

Currently we have two docs for installation: README.md and the Sage Installation Guide. There are severe problems:

  • README is too complicated for a beginner to follow: too many details, jargons, too many branch points (links)
  • There are many cross references between README and the Guide. One has to hop between the two docs.

This PR aims to make README.md a light-weight easy-to-follow installation guide for newcomers and beginners trying to install Sage to their personal computers.

See the new README:

https://github.com/kwankyu/sage/tree/p/streamline-installation-guide#getting-started

The new README does not try to be comprehensive. That is the role of the Sage Installation Guide. Materials removed from README are incorporated to the Sage Installation Guide. The Sage Installation Guide would provide all the details for users for whom the README.md is not sufficient.

The installation guide in README was tested with macOS, ubuntu, Windows WSL (ubuntu and fedora).

Along the way, I made extensive edits on the Sage Installation Guide. Most of them are non-technical.

See the new Sage Installation Guide:

https://doc-pr-38659--sagemath.netlify.app/html/en/installation/

In future, there would be little need to update the installation guide in README. Developers could focus only on updating the Sage Installation Guide as Sage evolves. This lessens maintenance burden.

📝 Checklist

  • The title is concise and informative.
  • The description explains in detail what this PR is about.
  • I have linked a relevant issue or discussion.
  • I have created tests covering the changes.
  • I have updated the documentation and checked the documentation preview.

⌛ Dependencies

#38676 to fix ci for doc preview

@kwankyu kwankyu changed the title Take out gory installation details from README.md and put them in Installation guide Move installation details from README.md to the Installation guide Sep 14, 2024
@kwankyu kwankyu changed the title Move installation details from README.md to the Installation guide Move installation details from README.md to the installation guide Sep 14, 2024
@kwankyu kwankyu changed the title Move installation details from README.md to the installation guide Move installation details from README to the installation guide Sep 14, 2024
@kwankyu kwankyu force-pushed the p/streamline-installation-guide branch 9 times, most recently from 0463362 to e55a675 Compare September 14, 2024 13:34
Copy link

github-actions bot commented Sep 19, 2024

Documentation preview for this PR (built with commit a5d5510; changes) is ready! 🎉
This preview will update shortly after each push to this PR.

@kwankyu kwankyu force-pushed the p/streamline-installation-guide branch from f3ea24e to ccd9dca Compare September 20, 2024 04:56
@kwankyu kwankyu marked this pull request as ready for review September 21, 2024 00:07
@kwankyu kwankyu force-pushed the p/streamline-installation-guide branch from b568039 to 4d0311d Compare September 21, 2024 00:40
@kwankyu kwankyu force-pushed the p/streamline-installation-guide branch from 4d0311d to 285a6ad Compare September 21, 2024 00:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant