Gentoo Archives: gentoo-dev

From: R0b0t1 <r030t1@×××××.com>
To: gentoo-dev@l.g.o
Subject: [gentoo-dev] Handbook Improvements
Date: Thu, 10 Aug 2017 01:13:12
1 Hello,
3 I am not a developer, but most of the discussion pertaining to the
4 handbook that has happened on user-oriented discussion forums has
5 never resulted in any changes.
7 Due to lack of recent inspiration, I have reproduced some of my
8 comments on a thread in gentoo-user below.
10 On Fri, Jul 28, 2017 at 8:44 PM, R0b0t1 <r030t1@×××××.com> wrote:
11 >
12 > Not to get away from OP's question, but how good would the installer
13 > need to be before it held the interest of any developers that manage
14 > the website or handbook?
15 >
16 > I ask because the much simpler thing I suggested - fleshing out the
17 > handbook - has been done and redone by some individuals and some of
18 > the guides are truly inspired. Unfortunately, I think it keeps being
19 > redone because these guides are hard to find and because the people
20 > who make them have no way to contribute to the handbook.
21 >
22 > Sakaki's EFI install guide, while very specific, is something that the
23 > majority of people who want to use Linux but don't want to maintain
24 > Portage seem to expect from the handbook. It actually tells them how
25 > to configure most of the things that produce a modern x86 system that
26 > interacts with a user. I mention it because it is the only guide I'm
27 > aware of that has persisted long enough to be indexed by Google that
28 > is also still relevant.
29 >
30 > The problem most people seem to have with Gentoo is not necessarily
31 > the installation process, but knowing what to configure after they
32 > have it installed.
34 I hope that serves as justification for the following proposals:
36 1) Migrate the Wiki to gollum ( which
37 would permit the management of the Wiki using Git and optionally pull
38 requests. Gollum is typically used with Markdown, though all current
39 articles could exported without being rewritten. Gollum is written in
40 Ruby and is used by GitHub.
41 2) If developer or user support is available, allow the addition of
42 architecture and device specific sections to the handbook. As it is,
43 the handbook mostly contains generic "extract the stage 3 tarball"
44 instructions for most architectures. Creating links to landing pages
45 that list various popular devices or installation scenarios inside the
46 handbook would help users by centralizing installation guides.
47 3) Since this documentation would be more closely associated with the
48 project, create some rough guidelines for content submissions.
50 R0b0t1.