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.