"What is FreeCAD" and "About FreeCAD"

Discussions about the wiki documentation of FreeCAD and its translation.
Forum rules
Be nice to others! Respect the FreeCAD code of conduct!
garya
Posts: 405
Joined: Tue Nov 20, 2018 1:00 am
Location: Ovando, MT, USA

"What is FreeCAD" and "About FreeCAD"

Post by garya »

There are two similar introductory pages, "What is FreeCAD" and "About FreeCAD". They overlap in some ways, where they discuss multi-platform aspects, free software aspects, etc. As a newbie, it feels like repetition if I encounter both of them when sequentially reading.
I see several options:
1. make the About FreeCAD page a side reference, not part of the serial reading
2. incorporate About FreeCAD into the What is FreeCAD page
3. leave it in place as the page following What is FreeCAD (still seems repetitive)
4. move About FreeCAD to the end somewhere (doesn't seem like a good idea given its current content)
My inclination is #2
If we go with #2:
2a. Eliminate About FreeCAD entirely; other references to the about page will obviously have to be updated.
2b. Leave About FreeCAD as is for reference by pages outside the manual, but still incorporate its content into What is FreeCAD
Thoughts?
User avatar
NormandC
Veteran
Posts: 18589
Joined: Sat Feb 06, 2010 9:52 pm
Location: Québec, Canada

Re: "What is FreeCAD" and "About FreeCAD"

Post by NormandC »

Hi Gary,

A tip: with the wiki button on the Reply toolbar, you can link a page name to the wiki. Select the page name in the text input area, press the wiki button. You'll get this:

Code: Select all

[wiki]About FreeCAD[/wiki]
which will render as About FreeCAD. Unfortunately, colons are not supported.

The page you're referring to is actually Manual:What is FreeCAD and part of the Manual.

As indicated in the Main Page, the manual "is another, more linear way to present the information contained in this wiki." It's kind of a "sub-domain" (in MediaWiki lingo it's called a namespace) with all its page names starting with "Manual:".

You can't assume that everybody will read the manual. I guess I'd go with option 2b because I don't agree with deleting or moving the About FreeCAD content.

That being said, you bring a very interesting point, and I think we should maybe think about this further.

I've come to think that the About FreeCAD content is really, really dry. It flings a lot of technical terms and acronyms and links that many, if not most newcomers will either have no interest in, or no frame of reference to understand them. I used to think it was important to mention commercial tools similar to FreeCAD, and the page includes Wikipedia links to them. Maybe we should stop giving them free publicity!

I think that Manual:What is FreeCAD is much easier to read.

So maybe we could take this opportunity to replace the About FreeCAD's content with the Manual:What is FreeCAD content. If you think its current content could be improved, all the better.

I understand that duplicate pages is not ideal, managing them separately would not be efficient nor fun. What could be done is to transclude (see Transclusion on MediaWiki) the About FreeCAD page in Manual:What is FreeCAD, in the same manner that templates are used.

In the Manual:What is FreeCAD, you'd replace the content with
{{:About FreeCAD}}
and you're done.

I made a quick try here that we'll delete when we're done (feel free to edit it and play with it):
Sandbox:What_is_FreeCAD
You will notice that there's some stuff that should not appear: the <translate> tags for one thing, and the Docnav template at the bottom. But we could easily get rid of them by editing the About FreeCAD page and adding transclusion markup so that they don't get transcluded. This is mentioned in the Transclusion page I linked above.

We could even for example keep the "About the FreeCAD project" section in the About FreeCAD page, but not have it appear in Manual:What is FreeCAD.

Any way, that's my two cents...

Norm
garya
Posts: 405
Joined: Tue Nov 20, 2018 1:00 am
Location: Ovando, MT, USA

Re: "What is FreeCAD" and "About FreeCAD"

Post by garya »

NormandC wrote: Mon Dec 31, 2018 11:39 pm A tip: with the wiki button on the Reply toolbar, you can link a page name to the wiki. Select the page name in the text input area, press the wiki button. You'll get this:

Code: Select all

[wiki]About FreeCAD[/wiki]
which will render as About FreeCAD. Unfortunately, colons are not supported.
Thanks, I think you've told me that before. I'm a slow learner :-)
If colons are not supported, then the "wiki" feature is more or less useless when referring to the manual? Or how should one use it if referring to the Manual?
As indicated in the Main Page, the manual ... with all its page names starting with "Manual:".
I thought the page immediately following What is FreeCAD was supposed to be Feature list, but maybe I'm confused from the About FreeCAD page. Should the Feature list be in the manual, in any case? I found it useful because it brought out some things not directly related to workbenches, but maybe not needed at that point in the manual. It also struck me as somewhat of a strange mixture of a few workbench highlights and general features, so maybe best left out at this point.
I've come to think that the About FreeCAD content is really, really dry. It flings a lot of technical terms and acronyms and links that many, if not most newcomers will either have no interest in, or no frame of reference to understand them. I used to think it was important to mention commercial tools similar to FreeCAD, and the page includes Wikipedia links to them. Maybe we should stop giving them free publicity!
I think that's a good idea. The one idea which seems relevant to me is that FreeCAD is not a 2D drawing app, and not an animation / organic shape creation app.
So maybe we could take this opportunity to replace the About FreeCAD's content with the Manual:What is FreeCAD content. If you think its current content could be improved, all the better.

I understand that duplicate pages is not ideal, managing them separately would not be efficient nor fun. What could be done is to transclude (see Transclusion on MediaWiki) the About FreeCAD page in Manual:What is FreeCAD, in the same manner that templates are used.

In the Manual:What is FreeCAD, you'd replace the content with
{{:About FreeCAD}}
and you're done.
Ah, got it. I like that idea a lot. It allows the navigation menus in the Manual pages without cluttering up the outside-the-manual pages.
I made a quick try here that we'll delete when we're done (feel free to edit it and play with it):
Sandbox:What_is_FreeCAD
You will notice that there's some stuff that should not appear: the <translate> tags for one thing, and the Docnav template at the bottom. But we could easily get rid of them by editing the About FreeCAD page and adding transclusion markup so that they don't get transcluded. This is mentioned in the Transclusion page I linked above.
Why wouldn't the <translate> tags be included?

Separate issue: Is there a way to shift text up to utilize the space to the right of the contents? Formatting-wise, it would be nice to have a short intro paragraph with a reduced image to the right of the contents.

I will try to work on all this tomorrow.
User avatar
yorik
Founder
Posts: 13640
Joined: Tue Feb 17, 2009 9:16 pm
Location: Brussels
Contact:

Re: "What is FreeCAD" and "About FreeCAD"

Post by yorik »

A sequencial, book-like manual is really something different than a wiki. One thing we learned with this wiki is that it quickly becomes extremely hard to keep its structure linear. This is the real nature of a wiki, to be a kind of shapeless propagating non-structured "thing".

That's basically why I started to write the manual, and why i did it outside of the wiki.

Of course we should always go for cleaning things, avoiding duplication, reuse components, etc, but I think we should always keep this "separation" in mind, otherwise very quickly we will loose the linearity of the manual. People will start linking and reusing and propagating its pieces in other structures, and soon impossible situations will arise where a same page should be at two different positions in the book or impossible to include. Believe me, there was a time when I tried to maintain the whole wiki linear :)

In this case, of course you are right, reading one of these pages after the other is silly. Maybe we should just consider both pages have different uses and remove the "About FreeCAD" link from the bottom of Manual:What is FreeCAD?
User avatar
NormandC
Veteran
Posts: 18589
Joined: Sat Feb 06, 2010 9:52 pm
Location: Québec, Canada

Re: "What is FreeCAD" and "About FreeCAD"

Post by NormandC »

garya wrote: Tue Jan 01, 2019 5:03 am Why wouldn't the <translate> tags be included?
<translate> tags are internal and should not show up in the page.

garya wrote: Tue Jan 01, 2019 5:03 am I thought the page immediately following What is FreeCAD was supposed to be Feature list, but maybe I'm confused from the About FreeCAD page.
Look at the Manual's table of contents. What follows after "What is FreeCAD" is Manual:Installing. Remember, every page that's in the Manual starts with Manual:. Any page that doesn't is not part of the manual but part of the wiki at large.

garya wrote: Tue Jan 01, 2019 5:03 am Separate issue: Is there a way to shift text up to utilize the space to the right of the contents? Formatting-wise, it would be nice to have a short intro paragraph with a reduced image to the right of the contents.
It should be doable, as can be seen for example here: PartDesign_Workbench. It does annoy me to have to scroll down so much because of the length of the TOC.

I also think it would be useful to collapse/expand the Manual's TOC as can be done with regular TOCs.

The problem is that the Manual's table of contents is a template embedding a template. Template:Manual:TOC is what is called in Manual pages; but its content is another template (Manual:Summary) inside <div> tags with a "toc" styling I have no clue how to search for. It's possibly a css style sheet somewhere.

Yorik is the one who created the stuff, so he'll be the one to answer that.
renatorivo
Veteran
Posts: 2611
Joined: Tue Feb 21, 2012 8:07 pm
Location: Torino - Italy

Re: "What is FreeCAD" and "About FreeCAD"

Post by renatorivo »

NormandC wrote: Tue Jan 01, 2019 6:22 pm garya wrote: ↑
Why wouldn't the <translate> tags be included?

<translate> tags are internal and should not show up in the page.
You can use the /en inclusion

Code: Select all

<languages/>
<translate>

<!--T:1-->
{{docnav|Manual:Introduction|Manual:Installing|Manual:Introduction|Manual index}}

<!--T:2-->
{{Manual:TOC}}

<!--T:3-->
{{:About FreeCAD/en}}

</translate>
garya
Posts: 405
Joined: Tue Nov 20, 2018 1:00 am
Location: Ovando, MT, USA

Re: "What is FreeCAD" and "About FreeCAD"

Post by garya »

yorik wrote: Tue Jan 01, 2019 3:14 pm A sequencial, book-like manual is really something different than a wiki. One thing we learned with this wiki is that it quickly becomes extremely hard to keep its structure linear. This is the real nature of a wiki, to be a kind of shapeless propagating non-structured "thing".
Agreed; that's also what makes it hard to use as an introductory / learning tool, and why the book is a good idea.
I think we should always keep this "separation" in mind, otherwise very quickly we will loose the linearity of the manual. ... Believe me, there was a time when I tried to maintain the whole wiki linear :)
You have my sympathy :-)! But I agree, keeping the separation in mind is important.
Maybe we should just consider both pages have different uses and remove the "About FreeCAD" link from the bottom of Manual:What is FreeCAD?
I agree the About FreeCAD link should be omitted.
But I also agree with Norm about the dry tone and less than useful enumeration of other projects and libraries aspect of the About page. I created a [wiki]Sandbox:About FreeCAD[/wiki] page that I think is probably more useful, mostly taken from reworked [wiki]Manual:About FreeCAD[/wiki] It seems to me that in this particular case, at least at the moment, it is usable as the About FreeCAD manual page as well.
I also modified norm's [wiki]Sandbox:What is FreeCAD[/wiki] page to use it, but as he pointed out, the template for transclusion doesn't seem to work with the colon so it's difficult to envision.
Thoughts?

I keep thinking once I get past this intro bit things will go smoother...
garya
Posts: 405
Joined: Tue Nov 20, 2018 1:00 am
Location: Ovando, MT, USA

Re: "What is FreeCAD" and "About FreeCAD"

Post by garya »

renatorivo wrote: Tue Jan 01, 2019 7:26 pm You can use the /en inclusion

{{:About FreeCAD/en}}
That doesn't seem to be any different than

Code: Select all

{{:About FreeCAD}}
What is "/en" supposed to do?

In any case, it doesn't seem to have any effect with

Code: Select all

{{Sandbox:About FreeCAD/en}}
renatorivo
Veteran
Posts: 2611
Joined: Tue Feb 21, 2012 8:07 pm
Location: Torino - Italy

Re: "What is FreeCAD" and "About FreeCAD"

Post by renatorivo »

with the (old)code

Code: Select all

<languages/>
<translate>

<!--T:1-->
{{docnav|Manual:Introduction|Manual:Installing|Manual:Introduction|Manual index}}

<!--T:2-->
{{Manual:TOC}}

<!--T:3-->
{{:About FreeCAD}}

</translate>
the <translate> tags are shown:
tag.png
tag.png (24.05 KiB) Viewed 1239 times
with the code shown above, the <translate> tags are not shown: https://www.freecadweb.org/wiki/Sandbox ... _FreeCAD_1
garya
Posts: 405
Joined: Tue Nov 20, 2018 1:00 am
Location: Ovando, MT, USA

Re: "What is FreeCAD" and "About FreeCAD"

Post by garya »

renatorivo wrote: Tue Jan 01, 2019 8:25 pm with the (old)code
...
the <translate> tags are shown:
...
with the code shown above, the <translate> tags are not shown
Thanks, I see now.
Post Reply