Great online documentation and/or wiki examples

Discussions about the wiki documentation of FreeCAD and its translation.
Forum rules
Be nice to others! Respect the FreeCAD code of conduct!
User avatar
NormandC
Veteran
Posts: 18589
Joined: Sat Feb 06, 2010 9:52 pm
Location: Québec, Canada

Re: Great online documentation and/or wiki examples

Post by NormandC »

yorik wrote: Fri Jul 20, 2018 2:32 pm The absolute majority of people who contribute a lot to the wiki are not the same people who touch the source code. And the contents in our wiki are pretty reasonable, compared to other projects. Not the best doc in the world, but far from the worst too. If we switched away from that, it's simple: we would hardly have any more new documentation. That's how FreeCAD works, some do the programming, others do community support (here, basically), and others manage documentation.
(...)
Of course we shouldn't go for anything that will prevent the level of accessibility and "translatability" that our current wiki has.
Thank you Yorik.

I understand the other issues, but if going the git way reduces accessibility and reduces translation capability, how exactly is it an improvement? More importantly, for whom? I have yet to see someone present us with a Git alternative that would keep our accessibility and translation capability.

sliptonic wrote: Thu Jul 19, 2018 10:03 pm A more modern documentation system like the gitbook model
Yorik's gitbook was left aside in favour of a MediaWiki version. Why was that?
User avatar
kkremitzki
Veteran
Posts: 2511
Joined: Thu Mar 03, 2016 9:52 pm
Location: Illinois

Re: Great online documentation and/or wiki examples

Post by kkremitzki »

One thing to note is that now that I am doing packaging work to improve freecad-doc, we have github.com/freecad/freecad-doc. This is basically a synced copy of the wiki available via Git.

I am using a tagging scheme like 0.17.20180720, i.e. <release.version>.<yyyymmdd>. This will solve the versioning problem since we can use these tags (and branches if necessary, e.g. after 0.18 and we need to make changes for 0.17 documentation).

Direct editing of the HTML files is possible if needed, i.e. if we need to fix the docs but don't want to have to change the wiki and pull down the changes.

Once packaged, these files will be available for posterity in the Debian archive too.

I think this mostly addresses the problems we have with Mediawiki, right? IMO it's better to try to focus on any such problems and work with what we have since I think that the marginal benefit of any switch would be outweighed by the cost of the switch.
Like my FreeCAD work? I'd appreciate any level of support via Patreon, Liberapay, or PayPal! Read more about what I do at my blog.
User avatar
bernd
Veteran
Posts: 12849
Joined: Sun Sep 08, 2013 8:07 pm
Location: Zürich, Switzerland
Contact:

Re: Great online documentation and/or wiki examples

Post by bernd »

@yorik: What is this done with, sphinx?
User avatar
yorik
Founder
Posts: 13640
Joined: Tue Feb 17, 2009 9:16 pm
Location: Brussels
Contact:

Re: Great online documentation and/or wiki examples

Post by yorik »

bernd wrote: Sun Jul 22, 2018 6:48 pm@yorik: What is this done with, sphinx?
With this: https://github.com/yorikvanhavre/FreeCAD-documentation

I sent this to some people here on the forum already to have a look, but got no feedback, so let's broaden the experiment :)
NormandC wrote: Fri Jul 20, 2018 7:46 pm I understand the other issues, but if going the git way reduces accessibility and reduces translation capability, how exactly is it an improvement? More importantly, for whom? I have yet to see someone present us with a Git alternative that would keep our accessibility and translation capability.
This is exactly what me and sliptonic tried to demonstrate with this github experiment: that it is as comfortable, or even more, to work in github than in mediawiki. There is of course the recent issue that github was bought by microsoft that annoys me a bit, but being git-based, it is easy to move somewhere else too later on.

Please have all a look at the link above and say what you think. It would not be a small work to do such a big move, but that's something to be studied and planned, if we all find it a good thing to try.
User avatar
NormandC
Veteran
Posts: 18589
Joined: Sat Feb 06, 2010 9:52 pm
Location: Québec, Canada

Re: Great online documentation and/or wiki examples

Post by NormandC »

yorik wrote: Mon Jul 23, 2018 4:58 pm There is of course the recent issue that github was bought by microsoft that annoys me a bit, but being git-based, it is easy to move somewhere else too later on.
But that would obviously mean losing the editing accessibility through the web, which is purely GitHub, not Git. GitHub supports markdown, Gitbook, adds a lot of stuff. I strongly doubt that much of that ease of use would be kept if moving to a GitLab instance. Then us non-coders would be really screwed. :|

OK, I'll have a look.

EDIT: a quick look at Gitbook left me puzzled. Apparently it started as an open-source project, but there is no code available anywhere that I could find. Only GitHub synchronization is possible. Is it wise to adopt a closed-source solution? A Git repo can be moved, but with Gitbook you have no such option. :|
User avatar
NormandC
Veteran
Posts: 18589
Joined: Sat Feb 06, 2010 9:52 pm
Location: Québec, Canada

Re: Great online documentation and/or wiki examples

Post by NormandC »

From https://docs.gitbook.com/v2-changes/imp ... ifferences
Git hosting and integration

We are no longer versioning your books as a Git repository. With the new version, we have shifted to a GitBook specific versioning system. Your content is still backed-up, versioned, and always available for export, so it is never locked on our platform. But we no longer offer this feature in the form of a git hosting service.

PDF and other ebook formats exports

The new version of GitBook no longer supports exporting to PDF and other ebooks format. A lot of rich-content does not translate well from the Web to PDF. GitBook will expose a developer API for people to consume and extend their content. It is not excluded that someone build a PDF export tool using the API, but it will not be officially supported. See the section about offline access if this is the part you cared about.

Multi-language books

The previous version of GitBook allowed having a language selector on the homepage, to choose between different translations of the same book. This is not yet supported. But this is a planned feature of the new GitBook, and it will be compatible with previous configurations.
User avatar
kkremitzki
Veteran
Posts: 2511
Joined: Thu Mar 03, 2016 9:52 pm
Location: Illinois

Re: Great online documentation and/or wiki examples

Post by kkremitzki »

NormandC wrote: Mon Jul 23, 2018 11:35 pm
yorik wrote: Mon Jul 23, 2018 4:58 pm There is of course the recent issue that github was bought by microsoft that annoys me a bit, but being git-based, it is easy to move somewhere else too later on.
But that would obviously mean losing the editing accessibility through the web, which is purely GitHub, not Git.
That may be true with GitHub but not with GitLab: https://docs.gitlab.com/ee/user/project/web_ide/
Like my FreeCAD work? I'd appreciate any level of support via Patreon, Liberapay, or PayPal! Read more about what I do at my blog.
User avatar
yorik
Founder
Posts: 13640
Joined: Tue Feb 17, 2009 9:16 pm
Location: Brussels
Contact:

Re: Great online documentation and/or wiki examples

Post by yorik »

kkremitzki wrote: Tue Jul 24, 2018 12:13 am That may be true with GitHub but not with GitLab: https://docs.gitlab.com/ee/user/project/web_ide/
Exactly. All these "we LOVE open-source" start-ups (github, gitbook, maybe crowdin soon, etc...) at some point or another, if they are successful, will get bought by a bigger firm and the party is over. But the point is, the git/markdown duo is becoming something pretty strong out there, there are many others, some open source some not. Same for translation, there is many others than crowdin, if the need arises. the fact is, a translated markdown page is just another markdown page, it is very easily portable to another system. Same for book publishing.

But I'm not trying to get you all convinced in one go ;) This is only to start the discussion.
User avatar
sliptonic
Veteran
Posts: 3457
Joined: Tue Oct 25, 2011 10:46 pm
Location: Columbia, Missouri
Contact:

Re: Great online documentation and/or wiki examples

Post by sliptonic »

There's a big difference between the 'new' gitbook and legacy. V2 is much more oriented to a commercial product. Legacy is more of an open source friendly model.

I haven't found one solution that does everything the way I would like but there seems to be a lot of players and projects moving in this direction (ie git plus some kind of friendly front end). Treating documentation like source makes sense for portability and version control. A friendly front end is absolutely essential if we want community contribution.

Fwiw, I spent a lot of time looking at solutions before starting the book. I ended up using rstudio and bookdown. This is NOT a solution for us (lacks the web editing solution) but if anyone is interested in doing a book, I would recommend it.
User avatar
bernd
Veteran
Posts: 12849
Joined: Sun Sep 08, 2013 8:07 pm
Location: Zürich, Switzerland
Contact:

Re: Great online documentation and/or wiki examples

Post by bernd »

yorik wrote: Mon Jul 23, 2018 4:58 pm
bernd wrote: Sun Jul 22, 2018 6:48 pm@yorik: What is this done with, sphinx?
With this: https://github.com/yorikvanhavre/FreeCAD-documentation
What software is used to create the nice documentation locally on my computer? Is this possible?
Post Reply