Hello everyone!
I am Gauri Maheshwari, and I have been selected as a GSoC mentee for this summer to upgrade the FreeCAD documentation system.
The project involves a lot of community suggestions and feedback, as it directly changes the documentation system and determines how we access it.
A strong open-source community, first-hand user experience, and user feedback are all important for improving the software, so I look forward to working with all the community members and contributors and learning from them
The proposal for the project is attached, and every suggestion or change is welcome and highly appreciated.
Have a look at the help system inside FreeCAD, how it works with the markdown format. Whatever solution we use, it will need to work well with that system
On the wiki, the contributors page here: https://wiki.freecad.org/Special:ContributionScores will give you an idea of who are the most active contributors of the current wiki. Not all these people have a github account and some are not used to work with git, markdown, etc. Basically we’ll need to find a solution that works well for everybody.
I am one of the Wiki contributors and will be following this project with special interest. If there are any questions related to the Wiki I will try to answer them.
Other most active editors on our wiki are mario52 , david69, Marco_T, uwestoehr, FBXL5, kaktus (and of course Roy_043 and kkremitzki). Guys, it might be interesting for you to keep watching this space
gauriimaheshwarii don’t hesitate to mention them whenever you need feedback from wiki editors.
This project is also a spacial interest for me. I’ll keep around and try to help as well!
I thought why not post regular updates of my work here only.
May 21, 2023 -
Tried integrating Gollum in the copy of documentation repository.
Faced challenges in setting up the wiki as on Windows, Gollum runs only on JRuby. Will try to run Gollum via Docker.
Set up a Wiki in the same repository as a sandbox project to allow the FreeCAD contributors to play around with the documentation and get familiar with the platform.
Made some progress on the website-like design for the wiki as discussed.
I’m very excited to see how this project goes: I am quite fond of Markdown, and I’m very frustrated by the poor search (particularly as it relates to translation) of the current wiki. I’ve looked a little bit at Docusaurus (which I think you have also seen) and it seemed to hold great promise. I hope you can find a good way to make a seamless transition from the existing documentation to a nicer platform. My understanding of the wiki translation is that it’s totally self-contained, right? There’s nothing being done on CrowdIn?
That’s right. And of course that’s one of the problems. We never know until when our MediaWiki translation plugin will work…
That’s very interesting. The git bla-bla is completely hidden from the user, and there is a sidebar with the page contents. I just tried setting one up too for GitHub - yorikvanhavre/FreeCAD-NativeIFC: A FreeCAD module to work with IFC files natively . What I like most is that it’s basically zero maintenance and platform dependency and extremely portable. I’d be curious to see if it can be ported “as is” to, for example, gitlab or gitea-based platforms like codeberg.org.
You can put files in subfolders, it stays so in the git structure, but you don’t use subfolders in links. Ex: a link to subfolder/mypage lokks like this: my page
We can give wiki write access either to anybody with a github account, or only to collaborators of the FreeCAD repo. This might be annoying as there is no fine-tuning possible (we would want not everybody to be able to write, but also not only people with write permission to the FreeCAD repo)
The wiki editing interface is the same as the normal markdown edit UI of github. So for editors there is not much advantage in using a wiki over a standard repo
Tried making the Getting started page in Markdown on GitHub Wiki and Docusaurus.
Check out the Wiki page here.
The Docusaurus website is currently available locally on my system. Attaching link to the screenshots here to show how the ‘Getting Started’ page looks.
Docusaurus allows viewing in both light and dark modes, and when clicked on ‘Edit this page’, it redirects to the GitHub repository where the file is located.
Kindly ignore the Tutorial Intro, Basics, and Extras sections on the left and the Blog section on the top.
That’s nice!
There is a demo version of docusaurus here: https://docusaurus.io/docs/playground
It has also built-in support for crowdin, that’s a huge plus.
I would like to see how the git repo associated with a docusaurus site looks like… If it is “portable” enough, that might be a very good solution.
Regarding PRs, if the documentation was on its own repo, we could do even better than on the current wiki: Trusted wiki editors have write permission, and can edit the doc directly, same as they currently do on the wiki, and occasional editors would go through PRs.
Hello everyone!
The project I am working on is upgrading the documentation system of FreeCAD with my mentor @kkremitzki.
For the new documentation of the software, we decided to go with Docusaurus because of several reasons, including the fact that it is git-based and open-source.
Till now, we have worked on the structure of the website, and have defined a layout for it. The first pages of each section and sub-section are made in a new way, though the linked pages still redirect to the current wiki. We are still working on the same, as every page is made manually and there are over a thousand files.
The website is viewable in both light and dark modes.
We are also looking at the possible ways to support multiple languages for the users.
There is still an issue of image sizes to be tackled.
Also, kindly ignore the tutorial tabs on the sidebar.
