[libre-riscv-dev] wiki usability issues

[Luke Kenneth Casson Leighton]

On Mon, Jun 17, 2019 at 10:10 AM Jacob Lifshay <programmerjake at gmail.com> wrote:

> the libre-riscv wiki needs to have the css modified to remove the dotted
> line on the right side of the screen, it interferes with wide tables.

 if you can track down the CSS that adds it, feel free to let me know
the change that's needed.  you should be able to edit it:
 https://libre-riscv.org/local.css


> also, pages are nearly impossible to find on the wiki without using google
> or some other search engine.
>
> If I can't find pages and I'm one of the main project contributors, that
> makes other people much less likely to be able to find much.
>
> if ikiwiki has the functionality, it needs to be enabled:
> 1. wiki-wide search (either built in or link to google site-search or
> something)

done.  needed libsearch-xapian-perl installed.

> 2. an index page with a link from the main page
> 3. each page to have autogenerated links to subpages under them, like a
> table of contents. only the direct subpages need to be listed, indirect
> subpages can be left out (though listing all subpages, direct or indirect
> would probably be a good idea if it's not too long).

 there's a way to do that using sitemap.  map directive.  found it.
added to the index.
 https://libre-riscv.org/sitemap/


> item 3 can replace item 2, but it's necessary to have either 1 and 3 or 1
> and a autogenerated table of contents that's linked to on every page.

 that's done by adding [[toc]] or something to each page, at a
location that the author of that page deems suitable.

> if ikiwiki doesn't have a way to automatically link subpages or some other
> method to improve discoverability, then I think we should seriously
> consider switching to a different documentation system, since we currently
> have the additional drawback of the wiki needing to be edited through
> cloning the git repo and people explicitly being given push permissions.

 no they don't - i edit the pages when i'm on the move on a regular
basis by logging in with a username/password.

 it works, and it works well.

> If we do need to change, I recommend linking to the wiki functionality in
> debian salsa, and just having a static html page for the main
> libre-riscv.org website that just links to salsa for the docs.

debian salsa domain != the libre-riscv.org domain.

it sends completely the wrong message to have authoritative resources
for libre-riscv managed completely by some other third party's domain.
storing data and resource on other peoples' servers says "we're not
competent or fit to run the project".

now, i have no problem with the resources looking like they came
straight out of the 1990s, on the basis that if people *really* want
better, they can *offer their time and resources to improve it*.

if they do not do so, then, well, they have no right to complain about
how it looks.

of course, *sigh*, in some cases, such as bugzilla, that *is* a pain
in the neck, as to do a safe upgrade it's necessary to a complete
off-site copy of the configuration *and* the data, perform the upgrade
on a test site, and then and only then if that goes well, perform the
upgrade "live".

l.