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.

Sign up for GitHub

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

To the point Onboarding #21

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

To the point Onboarding #21

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 31 additions & 13 deletions index.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,41 @@
/* -*- coding: utf-8; mode: php; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- vim:set fenc=utf-8 filetype=php et sw=4 ts=4 sts=4: */
/* Copyright (c) 2007, 2014, The MacPorts Project. */
include_once("includes/common.inc");
print_header('The MacPorts Project -- Home', 'utf-8');
print_header('The MacPorts Package Manager for macOS', 'utf-8');
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am a bit conflicted about "Package Manager" as MacPorts is a ports system. The difference might not be significant anymore...?

The term "The MacPorts Project" has always been the official name after the DarwinPorts rename and I guess that was well chosen with legal obligations in mind.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm using macports for years (thanks!), I don't know the difference between a ports system and a package manager. But this could be explained in an detailed page "what make MacPort unique" or "what is macport". Reading https://en.wikipedia.org/wiki/FreeBSD_Ports "The FreeBSD Ports collection is a package management system for the FreeBSD operating system".

My title proposition could certainly be improved, but it has to contain keyword people search for and the description on google need to feel familiar and easy. Today it's not very good:
Screenshot 2021-02-07 at 16 54 49

About using "The MacPorts Project", I understand the concern. Is this still a real concern? In day to day life people refer to "macports" right?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We are not a legal entity, but when we refer to our organization, we have generally used the phrase "The MacPorts Project". This organization develops and maintains a number of products and services: MacPorts base, the MacPorts ports tree, the MacPorts web site, automated build infrastructure including software called mpbb, etc. Together, these products and services make up the experience that is "MacPorts".

MacPorts was originally a ports system inspired by FreeBSD ports. A ports system builds software from source on the user's computer. In contrast, a package management system installs binary packages on the user's computer that were built by a server farm. MacPorts originally did not provide binaries, but did start doing so in version 2. But unlike most other package management systems, as far as I know, MacPorts will try to get a binary and if none exists it will try to build from source. As such, we are a kind of hybrid ports and package management system.

For simplicity, I tend to refer to it as a package management system, since that term conveys more meaning to a new user who is unfamiliar with either term. That's how I referred to it when I wrote up the short description of our project on the macOS forge landing page when I worked on decommissioning that service for Apple in 2016.

?>


<div id="content">

<h2 class="hdr">The MacPorts Project Official Homepage</h2>
<h2 class="hdr">MacPorts</h2>
<p>MacPorts is an open-source package management for macOS.</p>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Either "package management system" or "package manager" would be acceptable, but just "package management" is not.

Users may not know what this term means, so briefly explaining it here may be helpful, like I did on the macOS forge page. For example, "MacPorts is an open-source package management system that makes it easy to install, upgrade and uninstall software on your Mac."

There appears to be a misalignment on the h2 line (wrong indent).

<p>Latest MacPorts <a href="install.php">release: <b><?php print $macports_version_latest; ?></a></b></p>

<h3 class="subhdr">Install MacPort</h3>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We are "MacPorts", not "MacPort".

<ol>
<li>Install <a href="<?php print $guide_url . '#installing.xcode'; ?>">Xcode and the Xcode Command Line Tools</a></li>
<li>Agree to Xcode license in Terminal: <code>sudo xcodebuild -license</code></li>
Comment on lines +16 to +17
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These lines are indented by the wrong amount.

<li>Download and Run the MacPorts installer <a href="<?php echo $catalina_pkg; ?>">MacPorts-Catalina.pkg</a> (<a href="install.php#installing">other OS version</a>).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Run" should not be capitalized in the middle of a sentence.

Our installer packages always include version numbers. There is no package called "MacPorts-Catalina.pkg". It is currently called "MacPorts-2.6.4-10.15-Catalina.pkg". We should use the correct filename as the text of the link, or we should use descriptive words, for example making the link text "MacPorts installer for macOS Catalina" might be nice. Of course Big Sur is the latest macOS version so if we're only going to feature one here it should be the latest.

</li>
</ol>

<p>For more info and options see <a href="install.php">installation</a>.</p>

<h3 class="subhdr">Install a Package</h3>
<p><code>sudo port install packagename</code></p>
Comment on lines +24 to +25
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We call them "ports", not "packages". Users may not know this usage of the word "port" but adding a short sentence here to explain that should be sufficient.


<p>Everything installed by MacPorts is located in <code>/opt/local</code> and keep macOS clean.</p>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Grammatically the word should be "keeps" not "keep", but even so the sentence is not accurate. Many ports also install into /Applications/MacPorts, some install (symlinks to) launchd plists in /Library/LaunchDaemons, and some ports install files in other unusual locations—nothing prevents ports from doing so, other than our recommendation that they should not. Of course that's too much information for this introductory page, so we should keep it simple, but we should also keep it accurate.


<h3 class="subhdr">Update instealled Packages</h3>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Installed Ports", not "instealled Packages". If we're going to use title case for headers, then "Installed" would be capitalized as well.

<p><code>sudo port upgrade outdated</code></p>

<h3 class="subhdr">Help and Documentation</h3>

<p>Check our documentation, A.K.A <a href="<?php print $guide_url; ?>"> The MacPorts Guide</a>, and our Trac
<a href="<?php print $trac_url; ?>">Wiki server &amp; bug tracker</a>.</p>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see you carried this over from the previous version, but I would not capitalize Wiki here in the middle of a sentence, and aka or a.k.a. is written in lowercase and can probably be omitted entirely here. For example: "For documentation, visit the MacPorts Guide and our Trac wiki server & bug tracker".

<p>Feel free to <a href="contact.php">get in touch with us</a> if you run into problem using MacPort.</p>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"problems", not "problem". "MacPorts", not "MacPort".



<h2 class="hdr">The MacPorts Project</h2>

<p>The MacPorts Project is an open-source community initiative to design an easy-to-use system for compiling, installing,
and upgrading either command-line, X11 or Aqua based open-source software on the <a href="http://www.apple.com/macos/">Mac
Expand All @@ -23,17 +51,7 @@
There are <a href="<?php print $portdb_url; ?>">
<b>thousands</b> of ports</a> in our tree, distributed among different categories, and more are being added on a regular basis.</p>

<h3 class="subhdr">Getting started</h3>

<p>For information on installing MacPorts please see the <a href="install.php">installation</a> section of this site and
explore the myriad of download options we provide and our base system requirements.</p>

<p>If you run into any problems installing and/or using MacPorts we also have many options to help you, depending on how
you wish to get <a href="contact.php">get in touch with us</a>. Other important help resources are our online documentation,
A.K.A <a href="<?php print $guide_url; ?>"> The MacPorts Guide</a>, and our Trac <a href="<?php print $trac_url; ?>">Wiki
server &amp; bug tracker</a>.</p>

<p><b>Latest MacPorts <a href="install.php">release</a>: <?php print $macports_version_latest; ?></b></p>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe we can keep the version number in the download link above? I think it makes sense to state that somewhere.


<h3 class="subhdr">MacPorts Meeting 2019</h3>

Expand Down