btrfs.wiki.k.org and git-based update workflow

btrfs.wiki.k.org and git-based update workflow

[David Sterba]

Hi,

I'd like to change the way wiki contents is going to be updated, and
would like to get some feedback eventually.

Current status is quite unpleasant, the number of active editors is 1
(me), with other occasional contributions. I somehow feel that the wiki
concept as community editing does not work, specifically for our wiki,
or maybe in general, anymore.

I don't intend to remove the wiki, it's been linked from various places
and people are probably used to looking up the info there. What I'd like
to change is how the updates appear there.

I think the first hurdle is the separate registration. There's 1 new
account request per two weeks, but no actual edits following.

In addition to direct wiki edits, I'd like to provide a git based
workflow, on github. A separate repository would be clean but IMHO
harder to discover, so the idea is to reuse btrfs-progs for that purpose.

Selected pages from wiki will be "locked", with a disclaimer that they
need to be edited via git. Then in btrfs-progs/Documentation will be the
raw mediawiki source file. Edit this and send a pull request. I'll do
the sync to wiki periodically.

The manual pages are now synced like that, so this would allow us to
also use the asciidoc format as source.

For me personally using a local editor for writing documentation is much
more comfortable than the browser textarea. If this would motivate
someone else to contribute too, it's worth it.

(Other option researched: readthedocs.com, git-based but it has a
different structure than wiki and is on another site.)

d.

Re: btrfs.wiki.k.org and git-based update workflow

[Neal Gompa]

On Fri, Oct 22, 2021 at 10:14 AM David Sterba <dsterba@suse.cz> wrote:
>
> Hi,
>
> I'd like to change the way wiki contents is going to be updated, and
> would like to get some feedback eventually.
>
> Current status is quite unpleasant, the number of active editors is 1
> (me), with other occasional contributions. I somehow feel that the wiki
> concept as community editing does not work, specifically for our wiki,
> or maybe in general, anymore.
>
> I don't intend to remove the wiki, it's been linked from various places
> and people are probably used to looking up the info there. What I'd like
> to change is how the updates appear there.
>
> I think the first hurdle is the separate registration. There's 1 new
> account request per two weeks, but no actual edits following.
>
> In addition to direct wiki edits, I'd like to provide a git based
> workflow, on github. A separate repository would be clean but IMHO
> harder to discover, so the idea is to reuse btrfs-progs for that purpose.
>
> Selected pages from wiki will be "locked", with a disclaimer that they
> need to be edited via git. Then in btrfs-progs/Documentation will be the
> raw mediawiki source file. Edit this and send a pull request. I'll do
> the sync to wiki periodically.
>
> The manual pages are now synced like that, so this would allow us to
> also use the asciidoc format as source.
>
> For me personally using a local editor for writing documentation is much
> more comfortable than the browser textarea. If this would motivate
> someone else to contribute too, it's worth it.
>
> (Other option researched: readthedocs.com, git-based but it has a
> different structure than wiki and is on another site.)
>

It'd probably be good if we could eventually convert it to
Sphinx-based documentation like the rest of the Linux kernel
documentation. We could use readthedocs or reuse btrfs.kernel.org for
this.




--
真実はいつも一つ！/ Always, there's only one truth!

Re: btrfs.wiki.k.org and git-based update workflow

[Diego Calleja]

El viernes, 22 de octubre de 2021 16:12:00 (CEST) David Sterba escribió:
> Current status is quite unpleasant, the number of active editors is 1
> (me), with other occasional contributions. I somehow feel that the wiki
> concept as community editing does not work, specifically for our wiki,
> or maybe in general, anymore.

I would like to mention that I have tried to edit the wiki a couple of times
along the years, and somehow I was not able to get an account,  log in, or
recover my account (if I ever created one). Perhaps it's just me and others
can use it just fine.

In any case, it's worth noticing that the ext4 and xfs wikis are in worse 
shape, but with the improvements to the kernel doc infrastructure,
at least ext4 maintains some great documentation there instead of at the
wiki (eg https://www.kernel.org/doc/html/latest/filesystems/ext4/index.html)

It is also worth noting that while the kernel wikis are not very active, lots 
of semi-official content are generated in other places (eg the arch wiki).

Diego

Re: btrfs.wiki.k.org and git-based update workflow

[David Sterba]

On Fri, Oct 22, 2021 at 11:42:14AM -0400, Neal Gompa wrote:

> It'd probably be good if we could eventually convert it to
> Sphinx-based documentation like the rest of the Linux kernel
> documentation. We could use readthedocs or reuse btrfs.kernel.org for
> this.

The way sphinx docs are presented is a bit differnt (more linear whan
the wiki pages web), but I think it could improve discoverability of the
deeper pages. I'm not sure it's suitable for all the content that's
currently on the wiki, there are some free-form looking pages, but eg.
manual pages or FAQ are good candidates.

The only thing that bothers me is that spinx needs RST, yet another
markup language. I haven't found convertors asciidoc -> rst, but the
format is simple and some of the sturucture can be scripted.  It does
not conflict with the goal to have the sources in git and we could have
both output formats, wiki and readthedocs. So, thanks for the suggestion.

Re: btrfs.wiki.k.org and git-based update workflow

[David Sterba]

On Fri, Oct 22, 2021 at 06:36:33PM +0200, Diego Calleja wrote:
> El viernes, 22 de octubre de 2021 16:12:00 (CEST) David Sterba escribió:
> > Current status is quite unpleasant, the number of active editors is 1
> > (me), with other occasional contributions. I somehow feel that the wiki
> > concept as community editing does not work, specifically for our wiki,
> > or maybe in general, anymore.
> 
> I would like to mention that I have tried to edit the wiki a couple of times
> along the years, and somehow I was not able to get an account,  log in, or
> recover my account (if I ever created one). Perhaps it's just me and others
> can use it just fine.

There were problems with the accounts, some people did not receive the
confirmation email. Otherwise there's some odd behaviour after login and
editing pages it suddenly drops to some local account (shown as address
10.220.*) and page is not updated. Such things get annoying.

> In any case, it's worth noticing that the ext4 and xfs wikis are in worse 
> shape, but with the improvements to the kernel doc infrastructure,
> at least ext4 maintains some great documentation there instead of at the
> wiki (eg https://www.kernel.org/doc/html/latest/filesystems/ext4/index.html)

I think docs in kernel tree are not suitable for user documentation, so
it's probably fine for some internal design docs or on-disk structure
description, but otherwise I'd rather have something not connected to
the kernel git tree, if not only because of the different release
schedule and update path.

> It is also worth noting that while the kernel wikis are not very active, lots 
> of semi-official content are generated in other places (eg the arch wiki).

I'm aware of that and see it as a problem. One part is the 'official'
and reliability level of the information. I've seen to much copy&paste
from similar sources just repeating old and invalid advice, or
mentioning bugs that have been fixed or some bad usecase suggestions
that could do damage.

The other part is that there _are_ active editors and people able to
publish good docs, but how to lure them to edit the main community
wiki? :)

Re: btrfs.wiki.k.org and git-based update workflow

[David Sterba]

On Mon, Oct 25, 2021 at 03:34:16PM +0200, David Sterba wrote:
> On Fri, Oct 22, 2021 at 11:42:14AM -0400, Neal Gompa wrote:
> 
> > It'd probably be good if we could eventually convert it to
> > Sphinx-based documentation like the rest of the Linux kernel
> > documentation. We could use readthedocs or reuse btrfs.kernel.org for
> > this.
> 
> The way sphinx docs are presented is a bit differnt (more linear whan
> the wiki pages web), but I think it could improve discoverability of the
> deeper pages. I'm not sure it's suitable for all the content that's
> currently on the wiki, there are some free-form looking pages, but eg.
> manual pages or FAQ are good candidates.
> 
> The only thing that bothers me is that spinx needs RST, yet another
> markup language. I haven't found convertors asciidoc -> rst, but the
> format is simple and some of the sturucture can be scripted.  It does
> not conflict with the goal to have the sources in git and we could have
> both output formats, wiki and readthedocs. So, thanks for the suggestion.

A preview of the manual pages is here

https://deleteme12545.readthedocs.io/en/latest/

It's a temporary location because btrfs.readthedocs.io was not free but
I'm in the process of claiming it.

The RST is not much different from the asciidoc syntax so I converted
all the manual pages, the RTD is directly from the devel branch in
btrfs-progs. I'll full switch to RST after 5.15 release, there are some
formatting artifacts still to solve but right now the result is
pleasant.