I would like to introduce you to joplin-docs as a test for a new collaborative doc platform for Joplin. The objective is to unify the Joplin documentation. A user-friendly & qualitative area maintained by the community for new & advanced users where official doc and extended doc (best tips&tricks, howto) can live together.
More details available on the project homepage. I am curious to read your feedback, feel free to shoot the project. Any constructive reply is welcome.
At this stage I only have copied some pages from the docs and added sections to demonstrate the features, possibilities and the kind of content structure we can exploit.
It's just a proposal, and I am open to review any point of this project. I am new to Joplin and don't have a deep overview on it... please forgive me if I am a bit out of scope or too hurry here. I understand that an initial discussion/roadmap before rushing in a solution is important... and I don't want to bring confusion... so if it's too early to publish this subproject let me know and I will limit the access.
I publish it in an early stage as it's not worse than the current solution imho and we can't wait summer 2022 :).
Initially, I just wanted to post my feedback as 'a new Joplin user' and give a review of my firsts usage, but I ended by creating joplin-docs somehow . I saw the Refactor announcement once the job done and found the coincidence funny; illustrating quite well to current problematic
Roadmap proposal
add the existing docs and find a way to auto sync the /readme if it stays the official source.
extend the docs with the best tips & tricks, receipts from the forum posts and elsewhere.
docs.ovh.com use it for 4 years, +200 contributors (with a clean implementation on their website).
Quick tour
Author
Hi, I am Xaa, freelance web in Belgium. I tried Joplin in the past but migrated from EV only a month ago. I've found many helpful posts and tried to see clear on the documentation since my beginning. Joplin-docs is my way to thank you for Joplin and an attemp to contribute back to the project.
Thanks for sharing. We'd indeed like to have this kind of documentation with navigation on the left. A big part of this I think is to find a proper structure to organise all the existing Markdown doc files, then it would need to be automatically updated based on these files.
Also it will have to static html pages ideally so that we can host for free (and with excellent performances) on GitHub Pages.
Working on the documentation is a great idea. Right now relevant information is all over the place.
I think everything is better than a documentation in Discourse. Furthermore I think the documentation should become an official part of the project and replace the current help section on the website. Otherwise its just confusing.
The design with the left sidebar is great and pretty common for docs. Why did you choose GravCMS? Its a great a CMS, but maybe too much for simple docs? GitBook or MkDocs are possible alternatives which are tailor made for documentations.
I am still thinking about the structure of the documentation. Some random ideas, because I dont have a consistent vision: Do we really need a FAQ? Because the aim of a documentation is to answer most questions. So perhaps that would better placed on the Joplin website? Should Joplin Cloud as a "commercial" service be part of that documentation. Joplin Cloud users might have higher demands? I love theming as a part of the documentation, because there are many questions about it. Perhaps plugin maintainers could submit documentation for their plugins as well?
What about additional information about the different settings, common sync errors, switching the sync target, problematic Nextcloud hosting providers, a quick start guide, evernote import etc. How detailed should the developer documentation be?Just to name a few topics that are common in the forum.
A documentation of an other open Source project I like a lot is Zettlr's: Zettlr Docs
You raise good questions. I suggest the Refactor the project documentation initiative post to continue general discussion on the doc refactoring. Let's try to keep this one for joplin-docs.
I used Grav because I knew it and saw an opportunity for a quick start. A solution was almost build already. I will have a look at GitBook, MkDocs, thank you!
For me Grav is a light cms (maybe due to my Drupal & WordPress background) and I like how the content is managed (one folder by page to keep resources grouped).
Even if Grav is not the best choice, we can start building a better doc today using it (Importing the doc in the final solution should not be a big deal as content is .md files & folders).
A separate repo makes sense for me (as it allow quick merges, no risk to mess with the app, can evolve separately). If using xaa/joplin-docs is a concern (to stay in the "Joplin sphere"), Laurent could create the repo then I plug Grav on it.
.
Regarding your question about the FAQ:
At this stage I see it as temporary section where we can add the relevant posts from the forum pending the new doc structure is defined and approved. A complementary section living close to the general doc.
hi Laurent, thank you for your reply. I agree with your remarks. What do you think about the grav content structure management (see eg here? One folder by page. the file.md is the template name (chapter or doc).
I think Grav has plugins for static conversion. I may have a look.
Makes sense to keep the refactoring and the presentation in two different topics.
I have used Grav in the past for two or three smaller projects and really loved it. Its a great piece of software. I am just not sure if it is the best choice for a documentation, because there are so many other solutions available that are tailor-made for documentation. I have no experience with any of them, so I have no idea which is the best choice. I just wanted to raise the question and discuss it. Perhaps there is someone else with some experience?
. I saw the Refactor announcement once the job done and found the coincidence funny; illustrating quite well to current problematic 
