HowTo Pages for the Wiki?

Discussions about the wiki documentation of FreeCAD and its translation.
catman
Posts: 62
Joined: Fri Jan 11, 2019 10:42 pm

HowTo Pages for the Wiki?

Postby catman » Thu May 30, 2019 3:03 pm

I just noted that our Wiki does not have something like a central "HowTo" page. This would IMHO be very useful to put in information that is task and use-case based rather than WB reference based.
I remember very well when I learned my first CAD tool mostly from good HowTo descriptions. Even with courses, after the basics there are a lot of stoppers when doing standard tasks for the first time. Here a task oriented list is extremly helpful.

I feel it would be great to have this in the section that ends up in the installable help system. It could be similar to the FAQ but structured acording to tasks and/or workbenches. Maybe restructured a few times if it grows
Often simple things help, e.g.
- HowTo center a hole to a face? -> External geometry from edges and use symmetry constraint.
- HowTo Drill holes though different bodies -> bool subtract or use ShapeBinder.
- HowTo Dimension the distance between two hole edges? -> not selectable yet (FC 0.18).
- How to slice the 3D view? -> did not find out yet... ;)

What I mean is that should be different than the full tutorials: easier and quicker to write and add. Uses links to wiki pages rather than images. If someone liked a particular use cases from the help forum it should be a low barrier to just go in and add a few lines there.

First I though I just add a page, but then I think its better to propose this here for comments rather than messing up the wiki :oops:
So what do you think? Would someone be able to suggest where such a page may be placed and linked in?
renatorivo
Posts: 2154
Joined: Tue Feb 21, 2012 8:07 pm
Location: Torino - Italy

Re: HowTo Pages for the Wiki?

Postby renatorivo » Thu May 30, 2019 9:44 pm

HowTo.PNG
HowTo.PNG (32.38 KiB) Viewed 322 times
catman
Posts: 62
Joined: Fri Jan 11, 2019 10:42 pm

Re: HowTo Pages for the Wiki?

Postby catman » Fri May 31, 2019 8:30 am

renatorivo wrote:
Thu May 30, 2019 9:44 pm
HowTo.PNG
Can you explain what that means?
renatorivo
Posts: 2154
Joined: Tue Feb 21, 2012 8:07 pm
Location: Torino - Italy

Re: HowTo Pages for the Wiki?

Postby renatorivo » Fri May 31, 2019 9:12 am

catman wrote:
Fri May 31, 2019 8:30 am
Can you explain what that means?
Sorry, I didn't explain.
Add the "HowTo" element to the "Template: GuiCommand".
This allows you to create example usage pages, without making the command description pages too long.
A similar thing could also be introduced for some excellent examples that are scattered in the forum.
It's just an idea, maybe there are better ones ...
wandererfan
Posts: 2882
Joined: Tue Nov 06, 2012 5:42 pm

Re: HowTo Pages for the Wiki?

Postby wandererfan » Fri May 31, 2019 10:11 am

catman wrote:
Thu May 30, 2019 3:03 pm
First I though I just add a page, but then I think its better to propose this here for comments rather than messing up the wiki :oops:
So what do you think? Would someone be able to suggest where such a page may be placed and linked in?
If you just want to show a sample of what a howto page would look like, you can use the wiki Sandbox as here: https://www.freecadweb.org/wiki/Sandbox ... ign_fillet. There you don't have to worry about "messing up the wiki".

I like the idea of "mini-tutorials" or "task oriented tutorials" (aka HowTos). Not too big or intense - just enough to help avoid reinventing the wheel.

Edited for clumsy fingers.
catman
Posts: 62
Joined: Fri Jan 11, 2019 10:42 pm

Re: HowTo Pages for the Wiki?

Postby catman » Fri May 31, 2019 12:10 pm

wandererfan wrote:
Fri May 31, 2019 10:11 am
If you just want to show a sample of what a howto page would look like, you can use the wiki Sandbox

I like the idea of "mini-tutorials" or "task oriented tutorials" (aka HowTos). Not too big or intense - just enough to help avoid reinventing the wheel.
Edited for clumsy fingers.
Good idea.
Here is an example page: https://www.freecadweb.org/wiki/Sandbox ... _Use_Cases

I like the collapsable function, but I am not sure how well it scales for large pages. During edits it seems rather slow for large sections. Also to keep it tight you can not have too many empty lines in the source so all looks a bit messay with all the tags.
catman
Posts: 62
Joined: Fri Jan 11, 2019 10:42 pm

Re: HowTo Pages for the Wiki?

Postby catman » Fri May 31, 2019 12:12 pm

catman wrote:
Fri May 31, 2019 12:10 pm
wandererfan wrote:
Fri May 31, 2019 10:11 am
If you just want to show a sample of what a howto page would look like, you can use the wiki Sandbox

I like the idea of "mini-tutorials" or "task oriented tutorials" (aka HowTos). Not too big or intense - just enough to help avoid reinventing the wheel.
Edited for clumsy fingers.
Good idea.
Here is an example page: https://www.freecadweb.org/wiki/Sandbox ... _Use_Cases

I like the collapsable function, but I am not sure how well it scales for large pages. On my PC when I open the page it takes a few secs until all the sections fold. Also to keep it tight for the user you can not have too many empty lines in the source view. So all looks a bit messay with all the tags. Maybe there is a better way..
wandererfan
Posts: 2882
Joined: Tue Nov 06, 2012 5:42 pm

Re: HowTo Pages for the Wiki?

Postby wandererfan » Fri May 31, 2019 7:24 pm

catman wrote:
Fri May 31, 2019 12:10 pm
Here is an example page: https://www.freecadweb.org/wiki/Sandbox ... _Use_Cases
Just personal taste, but I would do 1 wiki page / howto, with a howto_contents page to collect them in 1 place. 1 big page is going to get unwieldy quickly.

The wiki-gurus may have other ideas.
catman
Posts: 62
Joined: Fri Jan 11, 2019 10:42 pm

Re: HowTo Pages for the Wiki?

Postby catman » Fri May 31, 2019 8:42 pm

wandererfan wrote:
Fri May 31, 2019 7:24 pm
Just personal taste, but I would do 1 wiki page / howto, with a howto_contents page to collect them in 1 place. 1 big page is going to get unwieldy quickly.
My worry would be that its really hard to get a separate contents page consistent. Primary concern would be for me to keep editing as easy as possible. My past experience with different pages never really worked out well.
For user browsing I think we agree that all items should be in a single list.
wandererfan wrote:
Fri May 31, 2019 7:24 pm
The wiki-gurus may have other ideas.
That would be most welcome
renatorivo
Posts: 2154
Joined: Tue Feb 21, 2012 8:07 pm
Location: Torino - Italy

Re: HowTo Pages for the Wiki?

Postby renatorivo » Wed Jun 05, 2019 8:15 pm

catman wrote:
Fri May 31, 2019 8:42 pm
My worry would be that its really hard to get a separate contents page consistent. Primary concern would be for me to keep editing as easy as possible. My past experience with different pages never really worked out well.
For user browsing I think we agree that all items should be in a single list.
catman wrote:
Fri May 31, 2019 12:10 pm
I like the collapsable function
The summary could be this: https://www.freecadweb.org/wiki/Sandbox:HowTo2