[libre-riscv-dev] wiki usability issues

[Jacob Lifshay]

On Mon, Jun 17, 2019 at 2:31 AM Luke Kenneth Casson Leighton
<lkcl at lkcl.net> wrote:
>
> 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
fixed. watch out for needing a full refresh, chrome didn't notice the
changes with just F5.
>
>
> > 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/
yay
>
>
> > 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.
isn't there a way to add some html that's added to every page? if
there is, maybe have each page link to the sitemap or something.
>
> > 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.
ah, ok.
>
> > 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".
ok, I was just thinking that gitlab has a pretty nice interface.
>
> 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*.
one part that might help that's easy to do is to switch the background
color to something other than light yellow, maybe to a very light grey
or white if you like light colors, otherwise, I'd recommend going with
a dark background and switching the text to white, which will be more
work.
>
> 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".
fun.