To the point Onboarding #21

gagarine · 2020-09-18T14:10:58Z

Make the text shorter and to the point to have MacPort up and running.

gagarine · 2020-09-18T14:13:59Z

In my opinion the section "The MacPorts Project" could me removed completely and add one small sentence in the top intro. But for the moment I moved this section down and focused on the top of the page.

I try to avoid jargon when possible.

raimue · 2021-02-07T15:28:28Z

index.php

@@ -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');


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.

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:

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?

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.

raimue · 2021-02-07T15:29:42Z

index.php


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


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

gagarine · 2021-02-07T16:01:13Z

I made this pull request some time ago. I will review it completely and push again taking into account the comments.

I did also some improvement on #23 (now closed) that I need to pull in this one:

Use h1 for page main title not for the logo
Remove h1 wrapper from the logo
Use alt in the logo, remove title

What do you think about the part "Getting involved: Students" + "Getting involved" is that somethings we can trim down too? Do we need to keep the Google Summer of Code logo or it's a requirement to have it?

ryandesign · 2021-02-07T19:53:47Z

index.php

@@ -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');


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.

ryandesign · 2021-02-07T19:54:12Z

index.php

-
-    <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>


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).

ryandesign · 2021-02-07T19:54:26Z

index.php

+    <p>MacPorts is an open-source package management for macOS.</p>
+    <p>Latest MacPorts <a href="install.php">release: <b><?php print $macports_version_latest; ?></a></b></p>
+
+    <h3 class="subhdr">Install MacPort</h3>


We are "MacPorts", not "MacPort".

ryandesign · 2021-02-07T19:54:54Z

index.php

+     <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>
+         <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>).


"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.

ryandesign · 2021-02-07T19:56:53Z

index.php

+    <h3 class="subhdr">Install a Package</h3>
+    <p><code>sudo port install packagename</code></p>


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.

ryandesign · 2021-02-07T19:59:12Z

index.php

+    <h3 class="subhdr">Install a Package</h3>
+    <p><code>sudo port install packagename</code></p>
+
+    <p>Everything installed by MacPorts is located in <code>/opt/local</code> and keep macOS clean.</p>


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.

ryandesign · 2021-02-07T20:00:43Z

index.php

+
+    <p>Everything installed by MacPorts is located in <code>/opt/local</code> and keep macOS clean.</p>
+
+    <h3 class="subhdr">Update instealled Packages</h3>


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

ryandesign · 2021-02-07T20:01:54Z

index.php

+    <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>


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".

ryandesign · 2021-02-07T20:02:22Z

index.php

+
+    <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>
+    <p>Feel free to <a href="contact.php">get in touch with us</a> if you run into problem using MacPort.</p>


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

ryandesign · 2021-02-07T20:09:22Z

index.php

+        <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>


These lines are indented by the wrong amount.

To the point Onboarding

c7aedda

Make the text shorter and to the point to have MacPort up and running.

raimue requested review from jmroot, neverpanic, ryandesign and raimue February 7, 2021 15:25

raimue reviewed Feb 7, 2021

View reviewed changes

gagarine mentioned this pull request Feb 7, 2021

Improve SEO and start cleanup front page #23

Closed

ryandesign reviewed Feb 7, 2021

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

To the point Onboarding #21

To the point Onboarding #21

gagarine commented Sep 18, 2020

gagarine commented Sep 18, 2020 •

edited

Loading

raimue Feb 7, 2021

gagarine Feb 7, 2021

ryandesign Feb 7, 2021

raimue Feb 7, 2021

gagarine commented Feb 7, 2021

ryandesign Feb 7, 2021

ryandesign Feb 7, 2021

ryandesign Feb 7, 2021

ryandesign Feb 7, 2021

ryandesign Feb 7, 2021

ryandesign Feb 7, 2021

ryandesign Feb 7, 2021

ryandesign Feb 7, 2021

ryandesign Feb 7, 2021

ryandesign Feb 7, 2021


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

		<h3 class="subhdr">Install a Package</h3>
		<p><code>sudo port install packagename</code></p>


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

		<h3 class="subhdr">Update instealled Packages</h3>

		<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>

To the point Onboarding #21

Are you sure you want to change the base?

To the point Onboarding #21

Conversation

gagarine commented Sep 18, 2020

gagarine commented Sep 18, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gagarine commented Feb 7, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gagarine commented Sep 18, 2020 •

edited

Loading