[gentoo-dev] Handbook Improvements

[R0b0t1]

Hello,

I am not a developer, but most of the discussion pertaining to the
handbook that has happened on user-oriented discussion forums has
never resulted in any changes.

Due to lack of recent inspiration, I have reproduced some of my
comments on a thread in gentoo-user below.

On Fri, Jul 28, 2017 at 8:44 PM, R0b0t1 <r030t1@×××××.com> wrote:
>
> Not to get away from OP's question, but how good would the installer
> need to be before it held the interest of any developers that manage
> the website or handbook?
>
> I ask because the much simpler thing I suggested - fleshing out the
> handbook - has been done and redone by some individuals and some of
> the guides are truly inspired. Unfortunately, I think it keeps being
> redone because these guides are hard to find and because the people
> who make them have no way to contribute to the handbook.
>
> Sakaki's EFI install guide, while very specific, is something that the
> majority of people who want to use Linux but don't want to maintain
> Portage seem to expect from the handbook. It actually tells them how
> to configure most of the things that produce a modern x86 system that
> interacts with a user. I mention it because it is the only guide I'm
> aware of that has persisted long enough to be indexed by Google that
> is also still relevant.
>
> The problem most people seem to have with Gentoo is not necessarily
> the installation process, but knowing what to configure after they
> have it installed.

I hope that serves as justification for the following proposals:

1) Migrate the Wiki to gollum (https://github.com/gollum/gollum) which
would permit the management of the Wiki using Git and optionally pull
requests. Gollum is typically used with Markdown, though all current
articles could exported without being rewritten. Gollum is written in
Ruby and is used by GitHub.
2) If developer or user support is available, allow the addition of
architecture and device specific sections to the handbook. As it is,
the handbook mostly contains generic "extract the stage 3 tarball"
instructions for most architectures. Creating links to landing pages
that list various popular devices or installation scenarios inside the
handbook would help users by centralizing installation guides.
3) Since this documentation would be more closely associated with the
project, create some rough guidelines for content submissions.

R0b0t1.