Guide theme update?

[Mojca Miklavec]

Dear Horst,

On Sun, 5 May 2019 at 16:15, Horst Gutmann wrote:
>
> I noticed that the main website today (or yesterday) got a little
> refresh with the bright blue tone being more prominent. Is someone
> already working on updating the guide's stylesheet to also reflect that
> change?

Se the answer by Clemens, as well as
    https://lists.macports.org/pipermail/macports-dev/2019-May/040674.html
with a bunch of links to brainstorming documents.

> If not, then I'd also like to update the typography there
> (larger font size with increased line-height). Would that be OK for you
> and what would be the process here? (I already found the correct repo on
> Github and am playing around with the stylesheet).

I'm not sure if anyone already touched the guide. Improving the guide
(ignoring the content improvements) would basically consist of three
semi-independent steps:

(1) We already have a bunch of auto-generated AsciiDoc documents which
we would like to use as definitive source as soon as possible. At the
moment the definitive source is DocBook [xml] and that's somewhat
non-trivial to edit. The conversion to AsciiDoc would need some loving
care to fix the conversion errors, but this is in fact an excellent
task for anyone new to MacPorts, and lots of people can contribute to
fixing such mistakes. With many people helping the conversion could be
faster.

(2) But before we ask people to start fixing mistakes in AsciiDoc
documents, it would probably help to have something that more or less
works (even if having plenty of conversion errors) and deploy a test
version to some temporary server. And then we need to decide when to
stop editing XML, run the final conversion to adoc and start fixing
the mistakes in the new document.

(3) Yes, we definitely need a better style for the guide! The only
question is whether that style would need to be any different if you
do conversion to html via DocBook or if you do it directly from
AsciiDoc (maybe some class names are different etc.), so it might be
that the change would need to be adjusted once the final switch to
AsciiDoc is done. It would be really awesome if we could manage to end
up with (almost) a single css style file that would apply to all the
pages (main page, guide, news, list of ports, ...) It's somewhat
suboptimal that the guide would need a completely different css from
anything else as is the case now.

> P.S.: I'm relatively new to macports as I've used it before about a
> decade ago but just rediscovered it a couple of days ago. I want to help :-)

I find it amazing that all of a sudden more than four people with some
designer instinct jumped in to help. We should definitely seize the
opportunity and do something awesome with the joined forces. Ideally
with some brainstorming first, followed by a concerted effort to
improve everything in a uniform, consistent and clear way.

Also: we really really really need a well-written section with "How
can I help?" (not using that title obviously, but something more
catchy). When the GSOC period started it was pretty challenging to
cater all the student and explain to everyone how to get started :) :)
:). A lot of that should have been obvious from some well-written
website. We also have a lot of people who find it difficult to write
and/or test the changes. We should definitely make it easier (and
easier to find) how to start contributing, either new ports or
something else, including design changes. We have lots of tickets that
require trivial changes to a lot of ports, for example, and that could
be done by any newbie, it's just not all that easy to dig them out.

Mojca