Refactor the project documentaton initiative

[xaa]

Hello Joplin community,

I am opening this post to start discussion on the "Refactor the project documentation" initiative. I didn't see this post soon enough and have already a first proposal.

Could you detail the expectations of the refactoring and give a roadmap, please?

The following info will be nice to know:

• What is the current solution?
• Do we keep the existing solution or an alternative is possible?
• Solution can be a side project or must be part of the main repo? (imho we should take advantage of github.com/joplin).
• How are managed the md generated dynamically (eg plugins list)? Is it "pluggable" to an external solution without too much effort?
• Others good-to-know?

Objective

The current documentation (under Joplin - an open source note taking and to-do application with synchronisation capabilities) is mainly a giant README.md file and various smaller Markdown files under /readme. All this is then built into the HTML website by a script.

We would like to improve this by splitting the main readme into smaller sections, have a new menu that would reorganise the help into various topics, and of course the build script will need to be updated.

A good part of this project will be about researching how other projects organise their documentation, proposing a way that would work well for Joplin, and discussing your ideas with the mentors and users. This is still a technical project though since you will need to deal with TypeScript, Markdown, HTML and CSS (and any other technology that might help) to build the new documentation. source

Roadmap

• tbd

Requirements

• tbd

Research

• ...
• Grav cms
• Github Pages
• Hugo cms
• ...

Proposals

Create a dedicated post with your proposal and link it here.
Keep this post for general discussion on the initiative.

[Daeraxa]

There has been a brief discussion on the topic, mostly surrounding using Discourse as an interim.

Added Wiki link in header

This is just to let everyone knows that I've added a Wiki link to the top header. For now it simply links to the "tips and tricks" tag but we could potentially link to a landing page or different tags. In fact if you have any suggestion on how to improve this, feel free to post here.

@xaa

What is the current solution?

Website published from the github readme docs + community supported Discourse wiki/how-to posts

@xaa

Solution can be a side project or must be part of the main repo?

I personally feel it should fall within the "official" Joplin sphere, either in the community (i.e. discourse) area or the "official" (i.e. website + github) area.

One of the nice things about having the official docs separated from the community content is that the barrier to entry for the community content is significantly lower (no need for github) and requires less time from repo collaborators to approve any documentation changes. The community content is simply able to be edited by more or less anyone at any time and allows for topics that you don't necessarily want as a front facing document on a website (for example my guide on how to un-delete stuff).