Ports' tips and gotchas

[Ben Woods]

On 4 January 2017 at 01:16, Vlad K. <vlad-fbsd at acheronmedia.com> wrote:

> On 2017-01-03 17:43, Adam Weinberger wrote:
>
>>
>> pkg-message needs to contain only essential information, otherwise
>> end-users will start to ignore them. I agree that tips should be
>> shared, but putting it into SVN isn't the way to go.
>>
>
> ...
> Unfortunately, random blogs and websites are not good enough because the
> information is "out there" and not immediately presented. However, now that
> you mention it, adding wiki entries and then having a pkg-message contain
> something along the lines of "Please consult
> https://wiki.freebsd.org/Foo/Bar for important information before you
> init/start/configure/migrate/update, ..." is a valid alternative and I
> like it. In fact, I'll be reworking my Postgres patch to do just that, and
> create an entry for Roundcube.
>
> However, what would be the best way to approach this via the FreeBSD wiki?
> I'm sure that random wiki pages in various users' namespaces is not quite
> the right thing to do. There currently are some ports Wiki pages but
> they're all over the place and not nicely organized.
>
> Perhaps it is time we start a special Ports namespace that would allow us
> to collate and list in one place all the user submitted wisdom and
> important instructions?
>


I wanted to chime in with a +1 for this idea.

I have often thought that the FreeBSD wiki should contain a space for ports
help wikis, that can initially be created by the maintainer, but other's
could also add their tips and tricks.

It is often said that FreeBSD has great documentation, but only if the help
you are looking for is in the handbook. For many ports this is not the
case, and projects like ArchLinux have far better documentation for how to
use their packages.

Some examples where the FreeBSD handbook and wiki have entries which don't
focus on explaining how the user should use the system / tips and tricks
associated with how to use it with FreeBSD:

Xfce - a few tips in the handbook, and porting status in wiki. Compare that
to the extensive help provided in the ArchLinux wiki.
https://www.freebsd.org/doc/handbook/x11-wm.html#x11-wm-xfce
https://wiki.freebsd.org/Xfce
https://wiki.archlinux.org/index.php/Xfce

Samba - a bit more detail in the handbook this time, but no where near as
much guidance as in the ArchLinux wiki:
https://www.freebsd.org/doc/handbook/network-samba.html
https://wiki.archlinux.org/index.php/Samba

Some examples from Arch Linux that I think would make great FreeBSD wiki
port help articles:
https://wiki.archlinux.org/index.php/Thunar
https://wiki.archlinux.org/index.php/ConsoleKit
https://wiki.archlinux.org/index.php/Polkit
https://wiki.archlinux.org/index.php/LightDM

So what I would like: agree on a place/structure for maintainers to add
"how to use this port / how it works / tips and tricks" information, and
let's get to writing some! The wiki is a great place, due to the low
barrier to entry, and low need to scrutiny due to it being somewhat
"unofficial" or unsanitised.

Regards,
Ben

--
From: Benjamin Woods
woodsb02 at gmail.com