Possible documentation to help people starting to use FreeCAD

Post here for help on using FreeCAD's graphical user interface (GUI).
Forum rules
and Helpful information
IMPORTANT: Please click here and read this first, before asking for help

Also, be nice to others! Read the FreeCAD code of conduct!
Halfa
Posts: 42
Joined: Fri Jan 08, 2016 3:40 am

Possible documentation to help people starting to use FreeCAD

Postby Halfa » Sat Jul 13, 2019 10:54 am

As mentioned in a previous post, I am struggling to learn FreeCAD because of the lack of documentation, and I believe others are having the same problems. There is a lot of very good documentation, but a lot of things have virtually none.
Sometimes I can go months before I can get back to FreeCAD, and with my memory not being as good as it was, (I'm 75), I started making notes to document what I had learned and why I did things certain ways, but decided that with more effort, I may be able to turn the notes into a useful document for people like me who have learned the basics of FreeCAD but have trouble as soon as they start on a "real" model.

I want to make a new Laboratory Power Supply and want to know if I can fit all the components in one of the instrument cases I have. My aim is to use this project to learn more about FreeCAD and hopefully test out the small milling machine I converted to CNC. My initial tests were done with G-code generated from drawings I did in Fusion 360 which is an excellent package, but I would prefer to use FreeCAD if at all possible. I am finding it a lot harder to learn than Fusion 360 because of inadequate documentation, and the work flow seems more confusing. I am not knocking FreeCAD or the few developers working on it. Fusion 360 should be much better with all the resources and experience AutoCAD has. The few developers and helpers have done a great job to get FreeCAD to where it is now. Seeing drawings done by ppemawm blows me away. FreeCAD can obviously do fantastic drawings - I just have to learn how.

I last tried FreeCAD over two years ago before I bogged down and changed to Fusion. Fusion also had the benefit of CAM which is now available in FreeCAD but in a much more limited way at this time.
With all the progress that has been, and is being made since my last try, I want to give FreeCAD a better try this time.

I have tried to use best practice but am having trouble finding out what that is. I know to avoid sketching on, or referencing surfaces whenever possible, although you can get away with it for simple jobs. Master sketches seem a good idea as is using Shapebinders to link to them. (What is a Shapebinder and why / when / how is it used? Searching didn't return information that was any help to me but eventually I found a good video that helped. I still know very little about Shapebinders but at least I have started to use them.)

Attached is the first draft of my enhanced notes as far as I have gone at present. They are only a start.
It is not a tutorial on drawing an instrument case but is more of a blog that shows some of the frustrations learners come across and how to overcome them in doing a project like this. Notes and tips are included where relevant to the current topic even if they aren't needed at this time in this project.
I plan for it to cover from starting to model the instrument case to assembling it and positioning the components, producing technical drawings, and using the Path workbench to generate code for milling out the front and rear panels and engraving the front panel.
Assuming my CNC mill tests out OK I hope to include photos and perhaps a video of the mill using the generated code.

The document needs checking to see if it is technically correct and close to best practice.
I don't want to take up too much time from experienced people, particularly developers, so I would like some feedback.

1. Does this document have the potential to be useful without tying up experienced people, or should I pull my head in and just make notes for myself and get a moderator to delete this post.
2. If it does have potential, how should I improve it from both a technical point of view and also from a learners point of view.

If I continue with this documentation I have a very long way to go, but with a little help hopefully I can get there and contribute to FreeCAD.

Halfa
Attachments
LabPowerSupply_1g.pdf
(629.18 KiB) Downloaded 45 times
User avatar
bejant
Posts: 5728
Joined: Thu Jul 11, 2013 3:06 pm

Re: Possible documentation to help people starting to use FreeCAD

Postby bejant » Sat Jul 13, 2019 9:11 pm

Halfa wrote:
Sat Jul 13, 2019 10:54 am
What is a Shapebinder and why / when / how is it used?
You can find more information here:
https://freecadweb.org/wiki/PartDesign_ShapeBinder
of see your Help documentation, if you downloaded it.


Halfa wrote:
Sat Jul 13, 2019 10:54 am
Assuming my CNC mill tests out OK I hope to include photos and perhaps a video of the mill using the generated code.
Thanks, and I'd like to see that!


Halfa wrote:
Sat Jul 13, 2019 10:54 am
The document needs checking to see if it is technically correct and close to best practice.
I don't want to take up too much time from experienced people, particularly developers, so I would like some feedback.
Ok, I'll have a look and I plan to reply again later.
Halfa
Posts: 42
Joined: Fri Jan 08, 2016 3:40 am

Re: Possible documentation to help people starting to use FreeCAD

Postby Halfa » Sat Jul 13, 2019 9:38 pm

Thanks bejant. I'd appreciate you having a look.

I had studied that wiki reference but I didn't understand how to actually use a Shapebinder. Ha Gei's video helped a lot, and I think it might have been another of his videos that used vertices to link references to a sketch "on a non-parallel plane". It shows using planes at right angles but does "non-parallel" mean I can project vertices or edges onto a plane at any angle? That is something I want to do in another project I'm working on.
Also I have seen a master sketch linked to by External References without a Shapebinder, so why use a Shapebinder. I suspect a Shapebinder is more versatile and can be used between bodies but I haven't had time to experiment to find out. Also, the term Shapebinder conveys an idea that it "glues shapes together " to an ignorant beginner. I'm not saying it isn't the most appropriate term to use, just that, to a beginner with his head spinning from all the videos and information he has read, strange terms like this can make you feel it is all too much. I don't know what the answer is but I thought my document that brings these terms in when needed and tries to explain why / when / how they are used could be useful.
I know my document has a long way to go and the content is not as good and clear as I would like, but achieving the quality of document I would like is, for me, a major job because I have to learn everything from scratch. Hence my request for feedback. I don't want to spend considerable time learning more than I need at present just to make a document that may be considered a waste of time by others

Halfa
User avatar
bejant
Posts: 5728
Joined: Thu Jul 11, 2013 3:06 pm

Re: Possible documentation to help people starting to use FreeCAD

Postby bejant » Sat Jul 13, 2019 9:54 pm

First read so far:

Page 1, Assumptions section:
Consider adding a hyperlink in the "excellent tutorial on the Sketcher by chrisb" text that links to the forum topic
https://forum.freecadweb.org/viewtopic. ... 04#p248329


Page Footer:
Consider using different / smaller text so that it is a bit more obvious that the footer text separate from the body text.


Page 3, Sketching section:
Consider adding a hyperlink in the "Sketcher Tutorial by chrisb" text as in Page 1.
Consider not referring to Length (Distance) Constraints as "Dimensions".


Page 4, Fillets and Chamfers section:
Consider including a more thorough description of the Solver functions inside the "(the algoritnm..." parentheses.


Page 4, Auto constraints section:
Consider mentioning that there is an "Auto Remove Redundants" setting.
Correct "Of Degrees Freedom" typo.


Page 4-5, Lines and Polylines section:
Consider including a hyperlink to the wiki page: https://freecadweb.org/wiki/Sketcher_CreatePolyline


Page 6, "Create a Body" section:
Here's a shortcut: for the first Sketch in the document, just clicking the Create Sketch" tool creates a new Body and upon completion of the Create Sketch tool the new Sketch is placed inside the new Body.


Page 6: I have a Solver message that I must respond to section:
Consider ticking the "Auto Remove Redundants" tickbox to True before placing the first segment.


Edit: Sorry, I didn't see you relied until after I posted so I'll respond to that later.
gonestefan
Posts: 2
Joined: Mon Jun 24, 2019 3:53 am

Re: Possible documentation to help people starting to use FreeCAD

Postby gonestefan » Sat Jul 13, 2019 10:35 pm

I think your document could be a very useful tool for intermediate freecad users. The documentation of the actual steps of your learning process is useful because it adds a human touch to the document and may well help to prevent others from going down waste-of-time paths.

I think you should keep the style of the document pretty much as it is now - you have written it in a friendly and accessible way. I appreciate that it takes a huge amount of time to produce something like this, especially with appropriate graphics, etc.

I would be happy to contribute ideas, suggestions, etc if you decide to go forward with your document.

All the best, Steve
Halfa
Posts: 42
Joined: Fri Jan 08, 2016 3:40 am

Re: Possible documentation to help people starting to use FreeCAD

Postby Halfa » Sat Jul 13, 2019 11:36 pm

Hi Steve,
Thanks for your support.
So far feedback is encouraging so it looks like I will be spending more time on the PC and less in the workshop for the forseeable future.
I will be trying to find the answers for myself but will appreciate your help and advice when I can't find what I need.

Arthur
TheMarkster
Posts: 997
Joined: Thu Apr 05, 2018 1:53 am

Re: Possible documentation to help people starting to use FreeCAD

Postby TheMarkster » Sun Jul 14, 2019 12:42 am

I'd like to see your notes on converting the mill over to CNC.

FreeCAD has a backup system where it creates .FCStd1, .FCStd2, etc. files. Default is only 1 file, but you can change that in Edit -> Settings -> General -> Document -> Number of backup files to create or some such.

I like the idea of putting the current filename as a default in the save as dialog. There is already a project information form saved in the document with a comment field. You can get to it via File menu -> Project information. It might be possible to have a way to edit that comment field within the save as dialog, too.

It's okay for the datum plane to be on the face, you just should not be mapping / attaching it to the face, if that makes any sense to you. The reason for this is when you map to a face you're mapping to the faces name, which might change if you go back and edit something earlier in the history tree. When the face name changes the objects mapped to it follow the name. This is referred to as the topological naming issue.

Personally, I don't use datum planes hardly ever at all. I just map the sketch to the plane, e.g. xy_plane, and set its attachment offset to what I need. For example, rather than map the sketch to the top face of the previous pad 10mm above the xy_plane I'll map the sketch to the xy_plane and set its z offset to Pad.Length. If I later elect for a different pad length the sketch will follow to the new position automatically. If it's on a different plane I'll use some value from a spreadsheet or sketch constraint. The thing about FreeCAD is there will almost always be multiple ways to do something.

I would recommend to start using spreadsheets now. If I were doing a tutorial on beginning to use FreeCAD I would probably have a spreadsheet in the very first lesson, or maybe the 2nd. You just need to learn 3 things to start using them: 1) how to create the spreadsheet --in spreadsheet workbench spreadsheet menu -> create spreadsheet; 2) how to create an alias -- right-click the cell -> properties -> alias tab; and 3) how to link to aliases in the spreadsheet via the expression engine -- press = key or click the f(x) icon -> enter Spreadsheet (or whatever label you gave it) dot (.) alias name. That's pretty much it if you've used spreadsheets in other applications then you already know what you need to know.

On the subject of spreadsheets, here's a tip for you. Label the spreadsheet ss in the tree view. Prepend ss to each alias. For example, you might have a variable called case_length. Give it the alias ssCaseLength. So, maybe you have ssCaseLength, ssCaseHeight, and ssCaseDepth as 3 variables you will be referring to in various sketches, among all the other variables you might have. It can be difficult to remember all the variable names, but by prepending the ss you can easily get a list of them as you're entering them into the expression engine just by entering =ss.ss. See the attached screenshot:
ss.png
ss.png (188.25 KiB) Viewed 309 times
The yellow cells in the spreadsheet indicate that these cells have aliases. We use aliases instead of, for example, Spreadsheet.B2, so we can say something like Spreadsheet.caseDepth.
Halfa
Posts: 42
Joined: Fri Jan 08, 2016 3:40 am

Re: Possible documentation to help people starting to use FreeCAD

Postby Halfa » Sun Jul 14, 2019 3:40 am

bejant,
Thanks for the suggestions.

Page 1, Assumptions section:
Consider adding a hyperlink in the "excellent tutorial on the Sketcher by chrisb" text that links to the forum topic

The underlined text is a hyperlink that works in LibreOffice but not in the PDF. I will find out why.
--------
Page Footer:
Consider using different / smaller text so that it is a bit more obvious that the footer text separate from the body text.

Good point. Only the Date and Page number is useful to people other than myself. The File info shouldn't be in the PDF although I will probably leave it there during development. It would be common sense to make the text smaller but I didn't think of it.
----------
Page 3, Sketching section:
Consider adding a hyperlink in the "Sketcher Tutorial by chrisb" text as in Page 1.
Consider not referring to Length (Distance) Constraints as "Dimensions".

It is a hyperlink but isn't working. I need to fix it.
I was trying to include words the learner would be familiar with and was planning to move away from the word "Dimensions" further in the document but I take your point. Maybe I mention at the start of the document that "What we might generally refer to as a Dimension is referred to as a Constraint in FreeCAD. Hence you have Distance constraints, Angular constraints, Radius constraints etc. Note that you have the option of Radius or Diameter constraints."
----------
Page 4, Fillets and Chamfers section:
Consider including a more thorough description of the Solver functions inside the "(the algoritnm..." parentheses.

I know nothing much about the Solver and its functions so I will have to study up on that and add something.
This is the ideal place to give some info on the Solver now that I have mentioned it. Not a complete description of it but enough info so that the word has some meaning instead of leaving the reader wondering what the heck Solver is. What I have said is probably a bit too basic.
----------
Page 4, Auto constraints section:
Consider mentioning that there is an "Auto Remove Redundants" setting.
Correct "Of Degrees Freedom" typo.

I vaguely remember some reference that "Auto Remove Redundant Constraints" may have a downside but that could just me being confused. I will find out more about it and add something.

Typo fixed. I don't know how the words got rearranged. I'll blame it on a faulty keyboard. It often spells words wrongly!!!
---------
Page 4-5, Lines and Polylines section:
Consider including a hyperlink to the wiki page: https://freecadweb.org/wiki/Sketcher_CreatePolyline

Yes.
---------
Page 6, "Create a Body" section:
Here's a shortcut: for the first Sketch in the document, just clicking the Create Sketch" tool creates a new Body and upon completion of the Create Sketch tool the new Sketch is placed inside the new Body.

Yes.
---------
Page 6: I have a Solver message that I must respond to section:
Consider ticking the "Auto Remove Redundants" tickbox to True before placing the first segment.

Sounds good but I want to know if there are any downsides so I can mention them if there are. As I have said, my memory isn't as sharp as it used to be and maybe I am wrong about a downside. Why is it an option if it is always the best way to go?
----------------------------

By the way, lines that are in coloured text indicate to me that I need to follow the subject up. It could be that it may be incorrect, that I need to learn more about it, that it may not be relevant or any use, or even total rubbish etc etc. The final document will probably only use colours for hyperlinks and things that the user may want to locate eg where each file Save As occurred so he can find that point and continue on from there.

I have thought of some kind of Index or Table of Contents, but at this stage I'm not sure what to list.
My first thought are new topics like the first time I create a Sketch, a Body, the External Reference tool, a Shapebinder etc. The problem with this is that I may expand on the topic somewhere else. Something I know nothing about is that maybe I can bookmark items and somehow include all references to the one topic in a reference table. That way you wouldn't have to search for all the places I might have used a Shapebinder in a different way.

I have roughly indicated what workbenches I am / will be using and will tidy this up. I can probably use headings and a Table of Contents to list some workbenches because they are pretty much separate eg Assembly, Path, TechDraw, but Part Design includes Sketcher, and I haven't got this far yet, but I understand there can be reasons to swap between Part Design, Part, and Draft so these aren't always separate as I see it at this stage.

Hopefully some of these things will sort themselves out as I learn more and write more documentation.

Another thing I need to look into is how I indicate updates and additions to the document because I don't want people helping me to have to read the whole document every time I submit it just to try to figure out what has changed. Possibly LibreOffice has the facility to put changed / added text in a different colour which I can then change back to black before the next update. So much to learn -- so little time.

I have a lot to learn about creating a worthwhile document. I don't even know if LibreOffice is the best software to use or should I be looking into something like Scribus. I find images and arrows pointing to things in LibreOffice, OpenOffice and Microsoft Office don't always finish up where they should be when I add / delete text.
The way I add icons is also a pain because they always need to have their Anchor and often Wrap options changed. Probably I'm not doing it the correct way.

Arthur

Edited first para LibreOffice not LibreCAD.
Last edited by Halfa on Sun Jul 14, 2019 4:47 am, edited 1 time in total.
Halfa
Posts: 42
Joined: Fri Jan 08, 2016 3:40 am

Re: Possible documentation to help people starting to use FreeCAD

Postby Halfa » Sun Jul 14, 2019 3:41 am

Hi TheMarkster,
Thanks for responding.
I'll dig out some photos and write a few notes on the CNC conversion for you in the near future. I have never sent a PM but I assume I can attach things. (More to look into.) The CNC mill is off topic so a PM may be the best way to go as I don't have a web site.

I knew about the backup system which is a good idea but its name doesn't convey the amount of info I like to have with a quick look. For decades I have used my file naming system for TurboCAD, Spreadsheets, Text files, Word processor documents etc and at a glance in the folder I can see when I made significant changes. Because the summary information is cumulative, having seen the date of a significant change (the numeric suffix has incremented) I can look back through the summary and see what the change was. I have found it very helpful.

I can't remember if I have mentioned the Topo naming problem but a mention probably wouldn't go astray. The way I have used Datum planes has been to offset them from an existing plane not from a face because of the topo naming problem as you said.

Interesting that you rarely use Datum planes. I will have to look into your method and try to compare the two ways. My initial thoughts are that a Datum plane may be more appropriate if there will be a number of sketches on it, but at this stage I haven't a clue. (More to look into.)

For this document I think I will hold off on spreadsheets, in fact I am rethinking the way the document is developing. Having drawn the top of the case, I am about to go back to the master sketch and add the bottom case outline. I think this is fair enough, but at the same time I was going to change to named constraints and expressions. After creating the bottom of the case I thought I might then go back and start using a spreadsheet.
I can see a beginner thinking "Great - I've drawn the top of the case. Damn, now I've got to learn about named constraints and expressions. Why can't I continue with the bottom of the case? OK I've done what I had to do to draw the bottom of the case and now I'm supposed to go back to the start to learn about spreadsheets whatever they are".

I think it would be better to mention named constraints and expressions and why we would use them, and also spreadsheets at appropriate parts of the document, but continue the document without using these ideas so the beginner can make continuous progress to a completed model.

With the beginner having had success this far, I can have a second document that starts at the beginning again (without as much hand holding on the parts covered in the first document) and introduce the more advanced topics of spreadsheets, named constraints and expressions, and perhaps other things I haven't thought about or know anything about at this stage. In other words a document for beginners and a separate document for semi-advanced users. A lot of the text etc in the first document could be copied across to the second document with the hand holding deleted. There would only be hand holding for the newly introduced topics.

I have noticed other people use two lower case letters as a prefix when naming objects in the tree. I didn't because I thought the icon was probably enough but I will go back and change the object naming to use the two-character prefix.

At present I will leave my personal notes and reminders at the bottom of the document just so I have ready access to them. When I have a workable document for others to use they will be removed along with the path and file info.

Arthur.
TheMarkster
Posts: 997
Joined: Thu Apr 05, 2018 1:53 am

Re: Possible documentation to help people starting to use FreeCAD

Postby TheMarkster » Sun Jul 14, 2019 4:06 am

Halfa wrote:
Sun Jul 14, 2019 3:41 am
Hi TheMarkster,
Thanks for responding.
I'll dig out some photos and write a few notes on the CNC conversion for you in the near future. I have never sent a PM but I assume I can attach things. (More to look into.) The CNC mill is off topic so a PM may be the best way to go as I don't have a web site.
You can post in open discussion board where the topics are a little more flexible. Just about anything goes there, and this is certainly CAD-related.