| 1 |
On Fri, Jul 28, 2017 at 8:53 PM, Rich Freeman <rich0@g.o> wrote: |
| 2 |
> On Fri, Jul 28, 2017 at 9:44 PM, R0b0t1 <r030t1@×××××.com> wrote: |
| 3 |
>> |
| 4 |
>> Not to get away from OP's question, but how good would the installer |
| 5 |
>> need to be before it held the interest of any developers that manage |
| 6 |
>> the website or handbook? |
| 7 |
>> |
| 8 |
> |
| 9 |
> That is hard to say. I've been meaning to better integrate the |
| 10 |
> systemd install guide into the main handbook for ages (to make it more |
| 11 |
> like how various bootloaders are supported in the handbook/etc). I |
| 12 |
> just haven't gotten around to it. Maybe now that I have a bit more |
| 13 |
> time on my hands I will. It sounds like EFI is in a similar |
| 14 |
> situation. |
| 15 |
> |
| 16 |
|
| 17 |
For reasons unrelated to this problem I think it might be a good idea |
| 18 |
to try to figure that out, because when I joined the mailing list |
| 19 |
quite a while ago there were some discussions about nonresponsive |
| 20 |
developers. I don't think anyone was being malicious, but if something |
| 21 |
requires that other people be present then it is immediately less |
| 22 |
likely to happen. |
| 23 |
|
| 24 |
What is unfortunate, and that may have been happening in the cases I |
| 25 |
remember, is that a developer was inadvertently given an obligation to |
| 26 |
do something without anyone realizing they were given that obligation |
| 27 |
- so then later someone wants to do something and they have to put |
| 28 |
forth effort whether they want to or not. |
| 29 |
|
| 30 |
> A lot of these docs end up being written as standalone docs to be read |
| 31 |
> alongside the handbook, and they don't get integrated. There is no |
| 32 |
> reason that the handbook can't have branch points at the appropriate |
| 33 |
> places. In both the case of systemd or EFI there are probably only a |
| 34 |
> few points where somebody has to do something differently so having a |
| 35 |
> standalone guide just makes the process more confusing. |
| 36 |
> |
| 37 |
|
| 38 |
If I'm right the only reason this is happening is because the Wiki |
| 39 |
articles are, like you later say, mostly inaccessible. |
| 40 |
|
| 41 |
> There was a proposal the other day to switch these kinds of documents |
| 42 |
> over to something other than pure Wiki markup to make it easier for |
| 43 |
> users to contribute. A wiki is nice in theory for user contributions, |
| 44 |
> but the problem is that many pages are locked down so that normal |
| 45 |
> users can't modify them, which defeats the purpose. That means that |
| 46 |
> it is actually harder for them to contribute, because they can't just |
| 47 |
> fork a document and contribute a pull request. It also makes it |
| 48 |
> harder for devs to make big changes because we can't just work on them |
| 49 |
> offline and get agreement before changing the main page. |
| 50 |
> |
| 51 |
|
| 52 |
My suggestion in this case is something that can render Markdown as |
| 53 |
HTML. I find Markdown documentation very readable in either form. It's |
| 54 |
also easy to track with Git and doesn't need any special tools besides |
| 55 |
a text editor to manipulate. It looks like the Gollum Wiki |
| 56 |
(https://github.com/gollum/gollum) project is a perfect fit. The |
| 57 |
project is used by GitHub and has seen widespread deployment. |
| 58 |
|
| 59 |
Will I be able to submit documentation PRs soon? |
| 60 |
|
| 61 |
R0b0t1. |
Archives