Date: Wed, 4 Jan 2017 17:50:51 +0800 From: Ben Woods <woodsb02@gmail.com> To: "Vlad K." <vlad-fbsd@acheronmedia.com> Cc: FreeBSD ports <freebsd-ports@freebsd.org> Subject: Re: Ports' tips and gotchas Message-ID: <CAOc73CCL8jqx-H4ABTLC2yU7c-cpCDrPtwTWex3LbJxG1yg8uA@mail.gmail.com> In-Reply-To: <76519193d791325700c3beb34b8f447b@acheronmedia.com> References: <c755791c3da66ff1329202cfa3bce52a@acheronmedia.com> <D2DCC023-1EBB-4444-AB59-81315EF239C0@adamw.org> <76519193d791325700c3beb34b8f447b@acheronmedia.com>
next in thread | previous in thread | raw e-mail | index | archive | help
On 4 January 2017 at 01:16, Vlad K. <vlad-fbsd@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@gmail.com
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?CAOc73CCL8jqx-H4ABTLC2yU7c-cpCDrPtwTWex3LbJxG1yg8uA>