the wiki: moving from 0.18 to 0.19 (bis)

Discussions about the wiki documentation of FreeCAD and its translation.
Post Reply
david69
Posts: 700
Joined: Wed Jan 01, 2014 7:48 pm

the wiki: moving from 0.18 to 0.19 (bis)

Post by david69 »

as one of the translators of the wiki, i came to the point how to manage the coexistence of 0.18 and soon the 0.19. in my mind it was a trivial question but no, if you read this short thread:
initially https://forum.freecadweb.org/viewtopic.php?f=21&t=53947

the question of how to manage documentation is not so simple in particular when the product evolves:
do we keep the actual model of the wiki? online editing
do we need to use special tools to generate documentation? sphinx, doxygen something else
how to manage versions? for example the GUI is changing, in 0.17 the introduction of body changed the habits and i don't speak about the future with some works like Realthunder's one in 0.20
and so on...

i open this thread because i think in the little corner of the wiki forum, there is not enough exposure and so may be here, some lights occur.

to the modo, if you think this thread is redundant with the above thread, feel free to remove this one.
drmacro
Posts: 4322
Joined: Sun Mar 02, 2014 4:35 pm

Re: the wiki: moving from 0.18 to 0.19 (bis)

Post by drmacro »

This is always an issue with revisions. (I remember having shelves of AutoCAD docs, one shelf for each revision. :mrgreen: )

Documenting the changes between revisions, and maintaining it as things evolve, is/would be a BIG project to do thoroughly...and endlessly.

I'm not sure it can be seamless and painless... :roll:

As a small contributor to the wiki, I would say I barely feel comfortable with the current editing process as it exists today (and I was around when markup language was invented... 8-) )

So, I wouldn't be thrilled with the idea of introducing some other tool that I need to go off and learn. (My toolbox in pretty full... ;) )
Star Trek II: The Wrath of Khan: Spock: "...His pattern indicates two-dimensional thinking."

My beginners, written treatise: Learning FreeCAD
User avatar
chennes
Posts: 1339
Joined: Fri Dec 23, 2016 3:38 pm
Location: Norman, OK, USA
Contact:

Re: the wiki: moving from 0.18 to 0.19 (bis)

Post by chennes »

Rather than putting this in the hands of individual authors, what about installing something like the Memento Wiki plugin? Then, the release versions of the software links to the wiki using the date they were released as the timepoint, and the website says that "Official documentation for the 0.19 release can be found here" and link to the same date. It might function sort of like a snapshot, from a user's perspective.
Chris Hennes
Pioneer Library System
User avatar
Roy_043
Posts: 3997
Joined: Thu Dec 27, 2018 12:28 pm

Re: the wiki: moving from 0.18 to 0.19 (bis)

Post by Roy_043 »

As I have already said in the other discussion, I think we simply lack the manpower to even consider this.

Also we should not forget that each FreeCAD version comes with its own offline help files which are based on the wiki. So you can already f.e. access the 0.17 version of the wiki, if you wish to do so.
chrisb
Posts: 38687
Joined: Tue Mar 17, 2015 9:14 am

Re: the wiki: moving from 0.18 to 0.19 (bis)

Post by chrisb »

Considering the amount of work and the number of workers, we can at most maintain one version. And that has, of course, to be the current. Even theoretically simple solutions, such as copy a frozen version when a release becomes stable, have do be managed.

I see very few questions in the forum, where people ask for things in 0.18 which are differently documented, because the respect already something in 0.19.
So my vote is to only document the current version, preferably with notes from which version on certain parts are valid. That enables us to write the documentation of new stuff while is still fresh.
A Sketcher Lecture with in-depth information is available in English, auf Deutsch, en français, en español.
chrisb
Posts: 38687
Joined: Tue Mar 17, 2015 9:14 am

Re: the wiki: moving from 0.18 to 0.19 (bis)

Post by chrisb »

Moved to Wiki forum.
A Sketcher Lecture with in-depth information is available in English, auf Deutsch, en français, en español.
User avatar
JoeKundlak
Posts: 50
Joined: Mon Oct 11, 2021 11:35 am

Re: the wiki: moving from 0.18 to 0.19 (bis)

Post by JoeKundlak »

Reg. potential versioning - I checked and found the MintyDocs extension for MediaWiki. I am not that versed in MediaWiki extensions to be able to tell how exactly it works (and the documentation did not reveal much to my untrained eye), but would this perhaps be a way?

Here is a copy-paste from the relevant page:
Defining structures
There are four basic types of pages within MintyDocs: product, version, manual and topic.
To define a new product page, you just need to add a call to #mintydocs_product to that page, directly or via a template.
A version page must be a subpage of a product page; an example would be "Product X/1.0".
A manual page must be a subpage of a version page; an example would be "Product X/1.0/Getting started".
Topic pages are usually a subpage of a manual page; an example would be "Product X/1.0/Getting started/Installing the software". However, topic pages can actually be placed anywhere; a topic can be used as a "standalone topic", so that it can be included in more than one manual.

Inheritance
One important feature of MintyDocs is inheritance: that is, you can have a page for a manual or topic simply display the contents of the same manual or topic for a previous version.

Let's say that you have three versions for a product: 1.0, 1.1 and 2.0. All three contain a manual called "Getting started". If this manual for version 1.0 is fully defined, then the page for the "Getting started" manual for version 1.1 can simply contain the following text:

Code: Select all

{{#mintydocs_manual:
inherit
}}

It will then display the same content as the version 1.0 "Getting started". Or you can add additional parameters to the #mintydocs_manual call - these will take effect, while everything that is not specified will be inherited.

The same goes for the manual in version 2.0 - if such a page is set to inherit, the code will go backward through the versions until it finds the first non-inheriting manual page (in this case, for 1.0) and inherit the content and settings from that.

This same logic applies to topic pages as well, which can also inherit from "earlier" topic pages.
Looking at it it would surely add some work to the mix (realigning all the pages and creating new ones), so please share your views if this is even feasible...
Last edited by JoeKundlak on Wed Nov 24, 2021 11:51 pm, edited 1 time in total.
Joe
---------------------------------------------------
translating into SK: https://wiki.freecadweb.org
hmk
Posts: 140
Joined: Tue Sep 29, 2020 1:19 pm
Location: Berlin, Germany

Re: the wiki: moving from 0.18 to 0.19 (bis)

Post by hmk »

Interesting find! It looks like something that might be feasible, I guess... Would be nice to see it in action at a larger Wiki though.
User avatar
JoeKundlak
Posts: 50
Joined: Mon Oct 11, 2021 11:35 am

Re: the wiki: moving from 0.18 to 0.19 (bis)

Post by JoeKundlak »

I am looking for examples...

Added the URL to my previous post.

EDIT: Found this page on WikiApiary: https://wikiapiary.com/wiki/Extension:MintyDocs.
It lists 4 webpages that use this Extension, but I fail to see the MintyDocs in action on those (perhaps they only have it installed, or at most do use it in an obfuscated way?).

MintyDocs builds upon PonyDocs, which the MintyDocs dev claims required some additional stuff, whereas MintyDocs does not and thus "should be better". PonyDocs was developed by the guys behind Splunk - https://docs.splunk.com/Documentation. That page might be the only real example of such implementation (uses versioning for their products), you can see it if you click for instance on any of their products like Splunk® Enterprise or Splunk® Universal Forwarder.

I have no Wiki on my own to test this (tried on Miraheze, but failed to really get anywhere - this might require a free hosting service and uploading a full MediaWiki there together with this plugin). I might still do it if I find a suitable hosting place...
Joe
---------------------------------------------------
translating into SK: https://wiki.freecadweb.org
Post Reply