Community run wiki

[AndreiSva]

We have so many packages in the community repository that it's getting hard to keep track of them. Not to mention that some of them require specific post-install steps to be taken by the user which currently are not really documented anywhere.

I've previously tried starting a wiki in this repository's Wiki tab, but I don't think hosting it on Github is a good idea for multiple reasons:

• Discoverability

  It's very difficult to find out about the existence wiki since it's hidden in a small tab in the website's repository, which not many people will ever visit. Even if there's a link added to the main page of kisscommunity.org about the wiki, it will mean redirecting the user to a different website which is a bad user experience.

• Github's wiki system sucks

  As of the writing of this issue, there are currently 401 packages in the community repository. While Github's wiki system might be fine for small wikis with only a handful of pages, Github wikis tend to be slow to navigate and cumbersome with a large number of pages.

• Hosting a separate wiki service like MediaWiki allows for more control

  Hosting our own wiki service would allow a much higher degree of control over who edits pages and how the wiki is set up in general. Furthermore, it has the potential to integrate perfectly with the rest of the community website and would give the opportunity of people without a Github account to contribute.

[dilyn-corner]

Something something fossil

[Riteo]

I agree that a separate wiki would be the right thing to do, but IMO we should follow kisslinux.org's way of doing it. This would also give us (hypotethically) the opportunity to put the wiki's files into /usr/share/doc/kiss (or just put them into their respective package) and let kiss help do its job.

[dilyn-corner]

It could certainly be a separate community-wiki package that is installed in the right place and setup in such a way kiss would know what to do with it.

[AndreiSva]

@Riteo, I've also considered that option. But how would people contribute / add their own wiki pages? kisslinux.org's wiki works well because Dylan is pretty much the only person contributing to it, but I'm not sure if that system would scale well with a lot more wiki pages and a lot more wiki page maintainers.

[Riteo]

@dilyn-corner that isn't a bad idea, but IMO we shouldn't immediately discard the idea of putting the documentation inside every package like core does. kiss-help only checks inside /usr/share/doc/kiss and the package's folder afterall.

[Riteo]

@AndreiSva every wiki page is just a file, I don't see why this shouldn't scale. If the issue is just updating the index then maybe we could make some script that builds it for us? It would still be lighter than a full-fledged mediawiki instance or something similar.

[dilyn-corner]

I'm certainly not opposed to people putting README's in their package's folder, but what I meant by

installed to the write place

is that the package installs all of the wiki documents to the requisite location in /usr/share/doc/kiss; unless what is ONLY meant by this PR is package-specific pages, in which case you're going to need to get every maintainer on board with supplying them.

[Riteo]

@dilyn-corner oh right, I forgot about the use case of non package-specific documentation, my bad. In that case IMO the best option would be to put the package documentation inside each package, while creating that community-wiki package for non package-specific pages. This should also make /usr/share/doc/kiss/ more tidy.

[jedahan]

+1 to putting non-package-specific stuff in /usr/share/doc/kiss/community[-wiki] to integrate with the rest of the system

[jedahan]

I would like to add a kiss-lint warning for packages missing help files, but it would require building packages which seems a little heavy-handed.

The next-best heuristic could be warning if all of the following files are missing (assuming that if they exist, build script installs them)

files/index.txt
files/${package}.txt
files/${package}
files/README

[jedahan]

And of course, if these files become 'standard' we can have a script that collates them all into a 'static' wiki, like dylan does for the regular kiss site

[AndreiSva]

Thinking about it now having the wiki page in READMEs inside the repository would be amazing! It would be a lot simpler and "KISS" than running a fully fledged MediaWiki instance but it would also allow for offline documentation! I love it

[aabacchus]

@ArmaanB and I have set up a community wiki system, live at https://kisscommunity.bvnf.space. A page for foo lives as index.md or index.txt in some directory foo/. The old kiss-community wiki has been imported and I am slowly converting some of it from plain text to the markdown dialect smu. GitHub pages was a monster, so for simplicity the website is served by a simple httpd from the wiki directory. On each push, make is run, which removes any *.html files or empty directories in wiki/, and then runs the build-page script for each directory.

If I know you well enough, drop me a message and I can give you push access to the repo on my server. Otherwise, you are welcome to open a pull request here, which I will merge manually (this repo on GitHub is just a mirror), or send me a patch via email.

Note: if you want to add a patch to smu, that's fine, just let me know before pushing because it won't apply automatically.