Joplin Community Wiki

Joplin Community Wiki

The topic has come up a couple of times recently about making a better "wiki" for the Joplin community. There is a conversation here which has prompted me to write this up a bit.
In my mind this is not the same as the main documentation for the reasons below:

Differences

Main docs

  • Should be the official "source of truth" for the project and therefore contributions need to be vetted and proactively moderated by the team
  • Should be concise whilst covering all of the essentials as this is essentially the "handbook" for all users, Joplin caters to a wide range of "technical literacy" levels so it needs to be correct for that audience
  • Should be relatively static as familiarity with navigating the docs for reference is important

"Wiki"

  • Should be community maintained with only a requirement for retroactive moderation to prevent malicious editing
  • Can contain far more verbose topics and can directly link to 3rd party/community created applications or tools without fear of making anything "official"
  • Can be as complex or as simple as desired depending on the intended audience
  • Allows for expansion on particular documentation topics which might have ever expanding links or guides or variations on the official guidance
  • Allows showcasing of community member's work better than the forum currently allows as it should have a far better browsing and searching experience

Solutions

Status quo

What we currently have is functional but perhaps not ideal.

Documentation is provided by a website built from .md files in the project's readme directory (and main readme file).

The wiki is provided by a link on the Joplin forum and consists of posts/topics that staff members have manually marked with the "how to" or "tips and tricks" tags.
It is a bit of a mess of standard forum topics with information and "wiki posts" which allow for community editing (although that concept is a very odd one on a forum and not that obvious to see the difference at a glance).

There is the potential for improvement on the wiki side in that new tags could be added to allow better categorisation or the addition of plugins such as Discourse Docs - the latter of which would probably require rethinking the Discourse hosting.

Pros:

  • We don't really have to put much work into changing anything
  • User authentication/moderation is combined with the existing forum security

Cons:

  • Current engagement of the wiki is low
  • Still requires Joplin team member interaction (although this is relatively easily solved)
  • Still feels a little "cludgy"

Static site

I won't go into details of the documentation side as the desire for improvement is covered by this year's GSoC project idea

One potential approach for the wiki is that the "consumer" side is served up as its own section of the main documentation website which, if we move to a more powerful CMS or SSG framework as is being suggested for the docs improvement project, often comes with inbuilt search functionality etc.

The "editing" side would therefore be served by an area open to the community for editing like the existing Wiki post/tagging system. This data could then be scraped, saved and pushed to the site in much the same way as the main docs just with a bot providing automatically approved PRs. I got this idea from this Discourse blog post

Pros:

  • Changes are mostly behind the scenes, no real change for users
  • User authentication/moderation is combined with the existing forum security
  • "One stop" place for articles and Docs
  • Should allow consistent theming and UI/UX
  • (Probably) no additional hosting costs

Cons:

  • Changes would likely not be reflected immediately
  • A fair amount of custom code/scripting required to provide the "bridge"
  • Slightly confusing as users aren't editing the articles "directly" so many might be hesitant to get involved

GitHub wiki

GitHub itself provides wiki functionality built right into it complete with searching, sidebar, repo integration (citation needed) and even the ability to easily clone the entire wiki for "offline" editing

Pros:

  • Simply requires turning on the function on a publicly available repo so little to no "backend" config required
  • User authentication performed entirely via GitHub accounts
  • Many are already familiar with the platform/UI/UX
  • No additional hosting costs

Cons:

  • GitHub isn't really used as a "community area" for Joplin so might be taking many outside of their comfort zone
  • Might be confusing as some may see the wiki is the "official" documentation for the project
  • Very little in the way of customisation to allow any theming or really much control at all

Dedicated wiki platform

The last option I can think of is a full on wiki platform with all the bells and whistles.
The kind of things I'm talking about are MediaWiki or (my preference) wiki.js

Pros:

  • Full on and mature wiki platforms with all the features you could possibly want from a wiki platform
  • Professional looking and with lots of configuration for theming, security, moderation, organisation etc.
  • Very user accessible for editing
  • wiki.js in particular fits very well with Joplin's technology stack (JS, node, docker, postgres)

Cons:

  • Might be overkill and "too powerful" for the size and scale of what we want to achieve
  • Entirely new platform for users (and admins) to get familiar with beyond that of the forums and GitHub
  • Has its own security and authentication which would require administration (some auth integration is possible with wiki.js with many popular platforms and social accounts supported)
  • Has hosting overheads unless there are any initiatives out there offering free hosting plans to open source communities

Ramble over

Thanks to anyone who has read this far through my ramblings. I'd love to hear what people think about these ideas in general as ultimately this is meant to be a community driven area so it only makes sense for feedback to be given by the community.

5 Likes

Regarding the "Status quo" option, one thing we could do is create a root wiki post that would be used to organise the other pages. That page could even be auto-generated using the API.

I don't know however if it would be worth it, whether people would find the information more easily and whether they would contribute more to the wiki.

It feels like the "Static site" approach would be a lot of work, and would not be a real wiki, so we probably wouldn't want that.

The GitHub Wiki is nice because we don't have anything to do, it's just there and working. The main drawback is that it's outside the forum and in fact many people post here various "how to", which we can then easily promote to wiki pages. But if it's on GitHub, it will be extra work to move the content, not to mention duplicate content (so it won't be as clear where to find the info anymore).

I'd add that one major problem with using GitHub for non-programming activities (e.g. wiki/documentation or discussions) is that non-technical users have got absolutely no idea how to navigate the site. In other words, the user interface on GitHub project pages is filled with programming jargon, and as such it is extremely overwhelming for someone accessing it for the first time. Non-tech people already struggle to find more obvious things like "Releases", so they will likely also struggle to find other things like the "Wiki".

1 Like

To be fair in that sense we don't need people to be able to find it from github as we can simply link directly to it from the forums/homepage/app or wherever else but one of the drawbacks is that GitHub in general scares people off as it is a place "for developers" and does have a rather... focused... UI.

1 Like