macports.org improvements

[constantin-p]

NOTE: Collaborative document for content: https://hackmd.io/s/BJwfLOToN

Suggestions:

A. DESIGN

1. Consistency between macports-www, /news (macports.github.io) and macports-guide

2. Support mobile devices (responsive layout, optimise navigation)

3. Modernise assets (logo/favicons/apple-touch-icon)

B. CONTENT

1. Improve navigation

• reduce the number of navigation links

2. Improve website copy

• remove/summarize content that overlaps with the documentation (e.g.: /install.php)

3. Improve UX for first time users

• keep the homepage simple:

A short sentence describing 'what does MacPorts do' Ports search bar Install [link] Getting Started/Quick Start [link]

• inspiration:
  • https://luarocks.org/
  • https://brew.sh/
  • https://rubygems.org/
  • https://crates.io/
  • https://yarnpkg.com/lang/en/

C. FUNCTIONALITY

1. Use the same system/repo for macports-www, /news (macports.github.io) and macports-guide (same writing format/publishing workflow)
2. Replicate 'Available Ports' functionality (or integrate the page - https://github.com/macports/macports-www/pull/14#issuecomment-489356921)
3. Offer the option to search ports from the homepage
4. Support content translation
5. Improve accessibility

D. NOTES

• use asciidoc as the default writing format

Drafts:

1. 5 May 2019 Design Prototype 1

• Notes:
  • responsive layout
  • same website for macports-www, /news (macports.github.io) and macports-guide
  • no content changes

  • missing functionality ('Available Ports')

    2: 19 May 2019 Design Prototype #2

[gagarine]

I made a pull request to simplify the index text. In my opinion it should even be shorter and perhaps have a short video/gif that show how nice macport is to install a software (like nodejs).

[constantin-p]

I agree, It could have the following structure:

A short sentence describing 'what does MacPorts do' Install [link] | Getting Started/ [link]

Below that we can show the three steps from 'Quickstart' horizontally with images under the first 2 steps and a table for the different download links as the last step.

---

Another point that I think is important is having a section describing the most common commands in a few words (e.g. https://yarnpkg.com/en/docs/usage). Currently you need to go to the documentation to find a description of basic commands (https://guide.macports.org/#using.port)

[constantin-p]

Collaborative document: https://hackmd.io/s/Bkm_jV3oE

[mojca]

Amazing guys, thank you very much for the initiative, and the suggestion list already looks like pretty much what we want!

I'm as-good-as-offline at the moment, but I should be able to send more feedback and suggestions by Tuesday or Wednesday.

[saagarjha]

Just a bit of feedback (I've been following the website redesign stuff not all that closely). Most of this will just be rehashing of an email I sent a couple months ago.

• Like the design. There are some small CSS tweaks that I might suggest but they're not all that important right now.
• The copy needs improvement: it ideally should just be a line or two of what MacPorts is, what using it looks like, and how to install it (the pull request helps quite a bit, but we should end up not having much more than this).
• Organizationally I the categories are a very good idea (I'm a bit iffy on "Getting Started", "Available ports", and "Downloads" being in the top menu; I was thinking of linking to them in the homepage copy and adding in things like "Contributing", "Support"), but we should ideally go through the content and arrange it better so it makes more sense.

[gagarine]

@saagarjha totally agree for the copy. I already made a pull request that remove most of the text from the index https://github.com/constantin-p/macports-site/pull/2 . I think it easier to remove text first and concentrate on what is important. Then we can always take piece from the "old" website if we feel their are missing. In my opinion, we should try to avoid technical jargon in the index as package manager are also used by junior.

Today junior are using homebrew because it look easier. I'm using port, because it IS easier and a lot more solid :).

I was thinking about adding a very short comparison with homebrew also (in the form of a list). But I would like to see the website published first before adding more stuff.

[saagarjha]

I already made a pull request that remove most of the text from the index #2 .

FWIW, I don't think these are being updated on https://constantin-p.github.io/macports-site/.

In my opinion, we should try to avoid technical jargon in the index as package manager are also used by junior.

I wouldn't shy away from somewhat technical phrasing–this is a package manager–but I do agree that it would be a good idea to not overdo it. And it's important to distinguish "technical", but important, content from "extraneous detail".

Today junior are using homebrew because it look easier. I'm using port, because it IS easier and a lot more solid :).

Tell me about it ;)

I was thinking about adding a very short comparison with homebrew also (in the form of a list).

I think it's important to answer the question of why you'd use MacPorts over Homebrew, but I'd personally not overdo it. A well-articulated statement that indirectly addresses the alternatives generally goes a lot farther than a point-by-point comparison, which might be perceived as petty or reactionary.

[constantin-p]

We can use this document to work on the copy for macports.org (that way we can have have multiple people review and change the content without having to wait or mess with build system). At the end of each day, if there are any changes I'm going to add them to the published draft.

NOTE: You should be able to edit the document with your github account. You can also leave comments without logging in.