Wiki staging environment set up!

Discussions about the wiki documentation of FreeCAD and its translation.
Forum rules
Be nice to others! Respect the FreeCAD code of conduct!
User avatar
kkremitzki
Veteran
Posts: 2511
Joined: Thu Mar 03, 2016 9:52 pm
Location: Illinois

Wiki staging environment set up!

Post by kkremitzki »

Howdy everyone,

I finally got a staging environment for the wiki set up:
https://freecad.io/wiki

I also did a little CSS experiment to change the way the table of contents looks on pages like the manual:
https://freecad.io/wiki/Manual:Introduction

Convenient comparison link:
http://freecadweb.org/wiki/Manual:Introduction

Feedback/testing appreciated!

If you have things you've always wanted implemented on the wiki, now's the time to let me know so I can try testing it.
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: Wiki staging environment set up!

Post by yorik »

Very good! I like your changes a lot.
Philip
Posts: 10
Joined: Thu May 18, 2017 7:59 am

Re: Wiki staging environment set up!

Post by Philip »

Hi! : )

I'm another newcomer to this 3D world. I've been learning FreeCad for a week now and have read part of the forums and wiki. Also I have followed some tutorials, of course. I'm no arquitect, no programmer and almost absolute beginner in 3D. But have been using Software Libre for 16 years now.

I thank all the people who have made this program and have contributed to the documentation. I also appreciate this move by @kkremitzki to make doc more digestible and accessible to newcomers.

Since I do have some experience with wikis over the past 12 years I have some comments to make on the topic:
  • - I miss a Discussion page parallel to the main so that its contents, proposals, trials and suggestions may be agreed before being incorporated into the main page.
    - Yes, a wiki maybe a good way to write and keep doc but it has to have a skeleton and not just fat and meat all mixed up.
    - There is no _one_ way to do things but many. A wiki can present its content in a variety of ways and they all complement each other.
    - Each page should do one thing "and do it well." If more pages are needed they are created.
    - I find unfortunate that this had to be written: "like most wikis, it contains huge amounts of information, but is very hard to access and navigate by newcomers." in https://freecadweb.org/wiki/Manual:Introduction. If it is hard then the contribuitors have not done a good job of _indexing it_ properly _and_ provided lists of links by topic and __routes__ to be followed by the user according to his/her interests at any given moment of consulting it.
    - A reference book/wiki is good for those who already use the program. A guide is needed for those attempting to grasp how to use the program. A tutorial is also good for those who do not like to read explanations but want learn through recipes. But these last are better suited for practical examples to create works, pieces o designs. A general index is also needed together with the search function.
    - A wiki page/group of pages for a version of the program. They cannot mix. If something has not changed a link to the previous will suffice.
    - The __user is the main target__ of the doc. And there are many types of users with many different needs at various stages of their learning experience. The wiki should care for the developer and for the casual user of the program, with all the in-betweens, by being a dictionary, a glossary, a guide, a tutorial, documentation, a manual and a virtual encyclopedia for the program, all together. Each in its own space and section.
Generally, all that is written in a wiki is useful. But it has to be ordered in its own page and this page listed in various places according to its contents.
The objective may or may not be to be proficient in using the program. It may be just to do one thing with it and not become an arquitect or 3D printer.
I stop there for now hoping I have touched the main elements needed for a wiki to be useful.

What I feel should not happen is what I'm now going through:
- I use Debian 8,
Freecad OS: Debian GNU/Linux 8.7 (jessie)
Word size: 32-bit
Version: 0.14.3702 (Git)
Branch: releases/FreeCAD-0-14
Hash: b3368125c63289ec8ce9faec2b2ae4c78d436406
Python version: 2.7.8
Qt version: 4.8.6
Coin version: 4.0.0a
SoQt version: 1.6.0a
OCC version: 6.7.0
- I have tried to follow the Draft Tutorial on the wiki, (I thought translating it to Spanish as I went along) but it requires "FreeCAD version 0.16 or above". And there are some things which don't work as described. I cannot know if because of the version, my lack of knowledge of the program or because the tutorial fails here and there.
- I had a look and tried to install this version but I had to add the repositories for http://ppa.launchpad.net/freecad-mainta ... le/ubuntu/
- I want to maintain my Debian as stable as it is and do not want to include any additional repos since I do not know how they will affect my system: too much trouble.

¿Is my system too old for FreeCad? There must be older ones on the planet. Especially in education centers and schools.
¿Is there not a tutorial for the 0.14 version?
I'll try to install FC 0.16 on another machine and test. But the _main tutorial_ "for Freecad" should work on any version. And if it differs on anything then a new version of the tutorial must be made. Then there have to be entries such as: "Tutorials for 0.14", "Tutorials for 0.15", "Tutorials for 0.16", etc. and not just "Tutorials."
It is work, yes, but Free Software such as FreeCad cannot risk loosing potential users right at the start, right? No users, no program. Dot.

If I had given up after the 2nd day with the program, the doc, the wiki and what I want now to accomplish (make a 3D model of a terrain and house) it would have been a loss for FC and Free Software. I want to learn and contribute.

I conclude for now: the wiki must have guides for each possible user with ordered links to each task. Not a book for each but lists of links to where the knowledge can be found. It is not as monumental as it sounds, it is ordering what is already there in different "views" of the same content.

Thanks for getting to the end ; )

Philip : )
renatorivo
Veteran
Posts: 2611
Joined: Tue Feb 21, 2012 8:07 pm
Location: Torino - Italy

Re: Wiki staging environment set up!

Post by renatorivo »

Wonderful! "Show Differences" and "Suggestions" are back. Thank you !!
traduzioni.png
traduzioni.png (43.81 KiB) Viewed 2055 times
Renato
User avatar
kkremitzki
Veteran
Posts: 2511
Joined: Thu Mar 03, 2016 9:52 pm
Location: Illinois

Re: Wiki staging environment set up!

Post by kkremitzki »

Philip wrote:Hi! : )

I'm another newcomer to this 3D world.
Indeed, welcome to the FreeCAD forums!
- I miss a Discussion page parallel to the main so that its contents, proposals, trials and suggestions may be agreed before being incorporated into the main page.
This is available on the top right of the header, click Page > Discussion.
- I find unfortunate that this had to be written: "like most wikis, it contains huge amounts of information, but is very hard to access and navigate by newcomers.”
Indeed, the problem is that it’s a huge amount of work to maintain with too few contributors, especially with the fast pace of FreeCAD development.
- A reference book/wiki is good for those who already use the program. A guide is needed for those attempting to grasp how to use the program. A tutorial is also good for those who do not like to read explanations but want learn through recipes. But these last are better suited for practical examples to create works, pieces o designs. A general index is also needed together with the search function.
Well, the Main Page right now has the hubs and a manual, which acts like a guide. I think the takeaway from this might be that having a few high-quality tutorials for the current stable version on the main page is a good idea, since many people might look for those first. Right now all I can see is the category being available: https://freecadweb.org/wiki/Category:Tutorials
but there really should be a curated “preview” table of recommended tutorials on the main page, with a few tailored to each of the main groups (users, power users, developers.)

- A wiki page/group of pages for a version of the program. They cannot mix. If something has not changed a link to the previous will suffice.
Indeed this is the way it should be, but there hasn’t been anyone to step up willing to do the actual work of maintaining such a thing. The idea is to use namespaces (a Mediawiki feature) going forward with 0.17 pages.
What I feel should not happen is what I'm now going through:
- I use Debian 8,
Freecad OS: Debian GNU/Linux 8.7 (jessie)
Word size: 32-bit
Version: 0.14.3702 (Git)
Branch: releases/FreeCAD-0-14
Hash: b3368125c63289ec8ce9faec2b2ae4c78d436406
Python version: 2.7.8
Qt version: 4.8.6
Coin version: 4.0.0a
SoQt version: 1.6.0a
OCC version: 6.7.0
This is a Debian packaging problem unfortunately. I recommend looking into AppImage, there’s a stable version build at https://freecadweb.org/wiki/download.
- I had a look and tried to install this version but I had to add the repositories for http://ppa.launchpad.net/freecad-mainta ... le/ubuntu/
- I want to maintain my Debian as stable as it is and do not want to include any additional repos since I do not know how they will affect my system: too much trouble.
Ubuntu PPAs generally won’t work with Debian, and when they do it’s a lucky coincidence. If you want stability I don’t recommend adding them.
¿Is my system too old for FreeCad? There must be older ones on the planet. Especially in education centers and schools.
It’s unlikely your system is too old. But I noticed you are running 32 bit and the AppImage is 64 bit. So that does complicate some things. If your computer is indeed 32 bit only you may need to do something more complicated. If that’s the case, I recommend making a new thread in the Install/Compile board for this issue.
¿Is there not a tutorial for the 0.14 version?

I'll try to install FC 0.16 on another machine and test. But the _main tutorial_ "for Freecad" should work on any version. And if it differs on anything then a new version of the tutorial must be made. Then there have to be entries such as: "Tutorials for 0.14", "Tutorials for 0.15", "Tutorials for 0.16", etc. and not just "Tutorials."
This is the way it should be but it’s a huge amount of work to do so. It’s hard enough keeping incorrect and out-of-date information off the wiki.
I conclude for now: the wiki must have guides for each possible user with ordered links to each task. Not a book for each but lists of links to where the knowledge can be found. It is not as monumental as it sounds, it is ordering what is already there in different "views" of the same content.
This mostly exists as the User, Power User, Developer hubs on the main page of the wiki.
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.
Jee-Bee
Veteran
Posts: 2566
Joined: Tue Jun 16, 2015 10:32 am
Location: Netherlands

Re: Wiki staging environment set up!

Post by Jee-Bee »

kkremitzki wrote:
What I feel should not happen is what I'm now going through:
- I use Debian 8,
Freecad OS: Debian GNU/Linux 8.7 (jessie)
Word size: 32-bit
Version: 0.14.3702 (Git)
Branch: releases/FreeCAD-0-14
Hash: b3368125c63289ec8ce9faec2b2ae4c78d436406
Python version: 2.7.8
Qt version: 4.8.6
Coin version: 4.0.0a
SoQt version: 1.6.0a
OCC version: 6.7.0
This is a Debian packaging problem unfortunately. I recommend looking into AppImage, there’s a stable version build at https://freecadweb.org/wiki/download.
check https://gist.github.com/berndhahnebach/ ... 967e6cdd36 @bernd have created an debian install script
User avatar
yorik
Founder
Posts: 13640
Joined: Tue Feb 17, 2009 9:16 pm
Location: Brussels
Contact:

Re: Wiki staging environment set up!

Post by yorik »

Philip wrote:Since I do have some experience with wikis over the past 12 years I have some comments to make on the topic:
Of course we all know this wiki is still far from perfect. But you should see how it was a couple of years ago! :D There have been huge progresses in the last year(s), slowly we will get there. If you have specific ideas over how the points you mention could be bettered, we're all ears! For example how you would achieve this:
Philip wrote:_indexing it_ properly _and_ provided lists of links by topic and __routes__ to be followed by the user according to his/her interests at any given moment of consulting it.
User avatar
NormandC
Veteran
Posts: 18587
Joined: Sat Feb 06, 2010 9:52 pm
Location: Québec, Canada

Re: Wiki staging environment set up!

Post by NormandC »

Everybody's a critic... You may find me sarcastic Philip, and I will not apologize for my attitude. In the 7 years I've been around this project, I've seen many people like you criticizing the wiki, but the common denominator with these critics (many of them asserting their experience with wikis or professional technical writing) is that none of them has ever stuck around and rolled up their sleeves to actually help to make it better.
Philip wrote:¿Is my system too old for FreeCad?
FreeCAD 0.16.670x is available in jessie-backports. https://packages.debian.org/jessie-backports/freecad

Otherwise, you chose a system for which stability is paramount, meaning it keeps very old versions of software. The problem is that FreeCAD is not a mature program, each version brings a staggering amount of new features as well as bug fixes. FreeCAD is not Blender or Gimp. It does not have an army of volunteers to keep info in the wiki on obsolete versions - and 0.14 is none other than that, an obsolete 3-year-old version. That being said, if you look at bejant's videos on YouTube, I believe they were made with that version.
Philip
Posts: 10
Joined: Thu May 18, 2017 7:59 am

Re: Wiki staging environment set up!

Post by Philip »

Hello : )
kkremitzki wrote: Thu May 18, 2017 11:51 pm Indeed, welcome to the FreeCAD forums!
Thank you. And thanks for your answers, Kkremitzki.
- I miss a Discussion page parallel to the main so that its contents, proposals, trials and suggestions ...
This is available on the top right of the header, click Page > Discussion.
I'm sorry I can't find that link in the tab on my browser. Maybe because I have not been able to register on the wiki? Are they accessible just adding "?Discussion" or something to the URL of the page?
- (...) "... but is very hard to access and navigate by newcomers.”
Indeed, the problem is that it’s a huge amount of work to maintain with too few contributors, especially with the fast pace of FreeCAD development.
I understand. It's the eternal never finished, ending task: _document_ ; )
If a developer wants his code to be used he/she has to explain how to use it. Not every user is a hacker.
- A reference book/wiki (...). A guide (...) A tutorial (...) but want to learn through recipes. (...) A general index is also needed together with the search function.
(...) a few high-quality tutorials for the current stable version on the main page is a good idea, since many people might look for those first. Right now all I can see is the category being available: https://freecadweb.org/wiki/Category:Tutorials
but there really should be a curated “preview” table of recommended tutorials on the main page, with a few tailored to each of the main groups (users, power users, developers.)
Yes. The list of tutorials is daunting to a newbie: "So, I have to follow at least a dozen tutorials before actually doing something!" It maybe that the entry level for FC is not as low as it is thought?
I think that what you suggest would reduce the number of tutorials, would encourage following them and would show the ideal type of tutorial wanted.
Out of the whole lot, the list nearing the hundred, which ones do you, experts in FC, consider them most useful and are the way in which the others should be re-written? That is, the recommended, high quality, "curated" tutorials. The rest simply exist and are so listed.
- A wiki page/group of pages for a version of the program. They cannot mix.
Indeed this is the way it should be, but there hasn’t been anyone to step up willing to do the actual work of maintaining such a thing. The idea is to use namespaces (a Mediawiki feature) going forward with 0.17 pages.
Well thought and concluded. New version, new namespace, section or update. If developers want their feature to be used they'll gather people to do it or will DIThemselves. Sorry to be so blunt but that's life: no users? no program. Or the code will be just a personal macro or script. No offense nor gratuitous criticism intended, ok?
What I feel should not happen is what I'm now going through:
- I use Debian 8,
Freecad OS: Debian GNU/Linux 8.7 (jessie)
Word size: 32-bit
Version: 0.14.3702 (Git)
This is a Debian packaging problem unfortunately. I recommend looking into AppImage, there’s a stable version build at https://freecadweb.org/wiki/download.
I'll look into it further see if I can use that. Thanks.
Well, problem? ; ) Debian 8.7 Freecad 0.14 works perfectly well. I started with the version my distribution has available, recommended procudure. No problem whatsoever. Using it has so far been a hit and miss, trial and error affair I'm afraid. In part it's my lack of knowledge and in part the lack of time and doc. But it works.
- (...) I had to add the repositories for http://ppa.launchpad.net/freecad-mainta ... le/ubuntu/ - I want to maintain my Debian as stable as it is and do not want to include any additional repos since I do not know how they will affect my system: too much trouble.
Ubuntu PPAs generally won’t work with Debian, and when they do it’s a lucky coincidence. If you want stability I don’t recommend adding them.
Yeap. If door knobs work no need to update them } ; )
It’s unlikely your system is too old. But I noticed you are running 32 bit and the AppImage is 64 bit. So that does complicate some things. If your computer is indeed 32 bit only you may need to do something more complicated. If that’s the case, I recommend making a new thread in the Install/Compile board for this issue.
[/quote]

New features? Fine, do I really need another machine and operative system? Maybe, but it has to be justified. Imagine I had a classroom with 30 boxes ... Thanks I only have 4!
And Freecad 0.14 _works_. Just that I have to find the way to be able to use it for what I want. Now and with this machine, which works, if I can't get another.
I have already started to (try to) use version 0.16 on a 64bits machine. Yes, on Debian ; )
And considered installing there the developer version. We'll see. But I do not know enough yet. But the 32bits is the machine I use and have not needed to change for, quite, a few years.
¿Is there not a tutorial for the 0.14 version?
I'll try to install FC 0.16 on another machine and test. But the _main tutorial_ "for Freecad" should work on any version. And if it differs on anything then a new version of the tutorial must be made. Then there have to be entries such as: "Tutorials for 0.14", "Tutorials for 0.15", "Tutorials for 0.16", etc. and not just "Tutorials."
This is the way it should be but it’s a huge amount of work to do so. It’s hard enough keeping incorrect and out-of-date information off the wiki.
[/quote]

I sympathise with the effort made and understand the loneliness of the few contribuitors.
The length of this response points to the way we tend to look at things.
I don't think information is out-of-date. It refers to this and that version of the code.
I agree, trying to keep _one unit_ of info up to date is really hard work. It is like adding elements to the program but maintaining the same version functioning in all machines and platforms permanently.
If there isn't a complete manual for 0.14, ok, there isn't. There are just these docs, tutorials, FAQs and the forum threads. But they _refer to the code_ being executed. Not to a new one where the existing instructions do not apply. I've already read (can't find now where) that for ver 0.17 "the old documentation does not apply" ... So, new one has to be created: more hard work.
_Com-pa-ti-bi-li-ty_. Either that or the new code needs explanations on how to use it. And it is developers who know the code inside out. Re-training users each time is out of the question. Coordinates and views have always stayed the same since I was trying to learn how to use AutoCad V.10 on a 486 machine.
Moving forward _all_ the time has a price.
I conclude for now: the wiki must have guides for each possible user with ordered links to each task. Not a book for each but lists of links to where the knowledge can be found. It is not as monumental as it sounds, it is ordering what is already there in different "views" of the same content.
This mostly exists as the User, Power User, Developer hubs on the main page of the wiki.
Yes, I've seen that. Good approach. I have not been able to delve enough into it not even qualifying as user yet.
User, Power User and Developer. Fine. Think about a fourteen year old guy trying to learn CAD. Or a housewife deciding how to re-arrange furniture at home, or a carpenter trying to pass his/her creations anto digital. He/She is a User, right? One cannot expect him/her to have used Blender, Sketchup, DraftSight, LibreCad or AutoCad and what not. He/She'ĺl have to learn the basics first. Unless FreeCad is only for Power Users with powerful machines and latest OS.

I'm trying to show a much more ample view of things and not just a program to print little pieces made of plastic fiber. If FreeCad is a "general purpose parametric 3D CAD modeler" it has to provide for the general public and user and not just for Power Users, geeks, nerds and hackers.
I saw today some videos by @microelly2. Great things he does with the program and very interesting area this Geo workbench. And there must be many more interesting areas I haven't seen yet. But the core of a CAD application is common to all of them. So it is this core I think has to be clearly and solidly exposed first. Further additions will be additions but the core is a must. And it may happen that it already is and I have not got to it yet.

Thank you, Kkremitzki, for explaining.

Philip : )
Philip
Posts: 10
Joined: Thu May 18, 2017 7:59 am

Re: Wiki staging environment set up!

Post by Philip »

Hello Norman : )
Everybody's a critic... You may find me sarcastic Philip, and I will not apologize for my attitude.
Not everybody ; ) I do not find your answer sarcastic and no need to apologize.
_My_ apologies if that is what my way of expressing opinions produced in you. It is not what I intended, please excuse me.
In the 7 years I've been around this project, I've seen many people like you criticizing the wiki, but the common denominator with these critics (many of them asserting their experience with wikis or professional technical writing) is that none of them has ever stuck around and rolled up their sleeves to actually help to make it better.
You must obviously have seen all sorts of communicants in that time, and suffered them too. I hope not to be thrown in the same bag with all the rest.
I see, 99/9/1: the readers, the writers and the contributor. Known fact proved over and over on the net. A new digit could be pre-pended nowadays : (
Philip wrote:¿Is my system too old for FreeCad?
FreeCAD 0.16.670x is available in jessie-backports. https://packages.debian.org/jessie-backports/freecad
Otherwise, you chose a system for which stability is paramount, meaning it keeps very old versions of software. The problem is that FreeCAD is not a mature program, each version brings a staggering amount of new features as well as bug fixes. FreeCAD is not Blender or Gimp. It does not have an army of volunteers to keep info in the wiki on obsolete versions - and 0.14 is none other than that, an obsolete 3-year-old version. That being said, if you look at bejant's videos on YouTube, I believe they were made with that version.
Exactly, paramount. Which doesn't necessarily mean very old. Just that they do their thing well.
I will try that backport. Thank you.
Sorry but, 3 years is obsolete? For an image viewer maybe but not for an ambitious project such as FC that tries to cover so ample and many fields. How long do you think it would take for an average User to be a proficient user of the program? Does he/she have to keep up with _every_ update?

Thank you for the info about Bejant's videos. I'll look into them again.
Personally I find more efficient a simple line such as Freecad > Edit < Preferences > Display > Selection > Preselection rather than having to guess/stop the video to figure where the little pointer clicked. But I maybe rare.
I'm already having a look at FC 0.16 on another machine, mind you.

I insist on apologizing, Norman. I try to never make gratuitous criticism but constructive. I seem to have failed this time. I'm sorry.

Philip : )
Post Reply