WARNING: Flurry of questions about to ensue...

[GrantRobertson]

Hello.

I recently discovered FreeCAD while searching for a 3-D drafting program that is better suited for creating mechanical parts than programs like Blender. I am particularly interested in the "parametric" nature of FreeCAD. I can see that the program has lots of potential to do lots of very powerful things. Unfortunately, I have found it very difficult to do any of those things because, as with lots of open-source projects, the documentation is seriously lacking. The help file is full of lots of detail but still doesn't truly tell you how to use the tools. I have read every tutorial I can find, but they all just skip over lots of very important information. As is often the case with software that has evolved slowly over time, supported by a small group of devoted fans, people have forgotten what it was like to not know many things. So they don't think to explain them in depth. Perhaps I can help with that.

I am a former technical writer with lots of experience using CAD software of many kinds. I was also a network manager and consultant for twelve years, so I know the kinds of things that regular people get tripped up on. I'm also working on a Master's in Computer Science. so I am not foreign to scripting or Python. I also just really want to have a decent CAD program that I can use to design my projects. Things like campers, cabinets, and other woodworking projects. I even know of several communities which would really be able to put a decent 3-D CAD program to good use. I think FreeCAD could be that program .... if I/they could figure out how to use it.

I was, honestly, just about to give up on FreeCAD altogether, but I decided to offer the community here a bit of a bargain: If I can get the folks here to answer all of my questions about FreeCAD, then I will write up a manual that will make it easy for regular people to learn how to use it. I'm not just talking about a couple of tutorials. I'm talking about a full-on book, explaining all the ins and outs of how to use FreeCAD, from beginner to expert. But these aren't going to be the normal, run-of-the-mill questions that you are used to getting here. These will be very specific, narrowly-focused questions about the internal workings of FreeCAD. And there will be lots of them. Lots and lots and lots. And many of them will seem pretty darned irrelevant to actually getting stuff done in the program. This is because it is only from this kind of deep understanding of the program that truly useful documentation can be written.

Now, some may say, "Why don't you just keep using the program and you will eventually figure it all out and then you can write your book." True. But that will take a hell of a lot longer than if I can get the people who already know all this stuff to explain it. That's the job of a technical writer: to grill the people who are already experts, asking questions about things those experts have forgotten that they know, and piecing it together into a good explanation that other, regular, people can understand. Some may also say, "Why don't you just look at the code? Then you will know how it works." The realists among us know it ain't that easy. Besides, I'm a Java guy. I hate C++ with a deep purple passion.

So, what do you all say? Are you willing to give it a shot?

[bejant]

I decided to offer the community here a bit of a bargain: If I can get the folks here to answer all of my questions about FreeCAD, then I will write up a manual that will make it easy for regular people to learn how to use it. I'm not just talking about a couple of tutorials. I'm talking about a full-on book, explaining all the ins and outs of how to use FreeCAD, from beginner to expert.
(snip)
Are you willing to give it a shot?

Sure - If I provide meaningful answers for free can I have a .pdf copy of your book for free? Even if the answer is "no", post your questions anyway and you'll get ample help.

[ppemawm]

the documentation is seriously lacking

I do not know if you are aware of the professionally produced FreeCAD Manual written by Yorik : https://yorikvanhavre.gitbooks.io/a-fre ... l/content/
I am sure it will be of great help to you if you are just beginning FreeCAD although it does need an update for Version 0.17/0.18.

There is also this book available on Amazon of which you may not be aware: FreeCAD-How-To by Daniel Falck which is, however, sadly out of date.

IMHO CAD is best learned by practice, practice, practice. Most of the new users who have trouble do so not because of a lack of serious documentation but simply because they do not spend the necessary time to become proficient with the basics. They usually try to jump in with complex models right from the start instead of learning properly by first creating 100's of simple models that slowly progress through all of the tools that FreeCAD offers. I have also had the same experience with FEA and CFD users.

I came from the Unigraphics world and actually survived implementation of this high end software in a large global organization. We managed the conversion of a large group of mechanical board drafters to about half as many full-on parametric solid modellers integrated with CAM over a period of about 10 years. In my experience documentation was not the biggest problem. As we used to say, "you can buy them books and buy them books but all they do is eat the covers." You simply must put in the hard time.

[GrantRobertson]

Sure - If I provide meaningful answers for free can I have a .pdf copy of your book for free?

Perhaps I should have been more clear. Yes, I do intend for this to be an open-source book, with a creative commons license. The primary purpose of writing the book is for me to learn the software. That is how I learn things. As I learn it, I write up extensive notes, suitable for teaching others. If I can't explain it in a manner that would make it easy for others to learn, then I don't understand it well enough myself. The secondary purpose of writing the book is to have something to show off to get writing contracts. Just as software developers often "make their bones" by contributing to open-source projects, Technical writers often write manuals for open source projects. Unfortunately, really good technical writers are even fewer and farther between than really good software developers. And it is easy to just churn out a bunch of words and not really produce anything useful.

[freedman]

I would really like to see one document:
1) FreeCad for Beginners.

This way the volunteers here wouldn't have to waste hours and hours of their lives answering the same questions over and over. I felt bad when I started so I try to help out some by answering questions if I can. I think just about every question on usage has been asked and answered many times over. That might be your best resource, review the last 5000 comments in the Help section.

I don't think a book can be finished until Assembly is included, it's hard to document something that's not complete.

I know of at least 5 Solidworks books with thick dust sitting on them. Learning CAD is like learning to ride a Dirt Bike or Skiing, it turns into an artform in your mind, we don't pick up a manual until we run out of technique and patience.

[mrdic]

Whatever your motivation, ask your questions. There's often an intuitive disconnect between what tools do and what some people think they should do, and it's very possible that your difficulties result from that situation. That's complicated by users often finding ways to use tools that even the coders hadn't considered. Why not ask about the things that you're struggling with and see what comes of it, disconnected from other ambitions? It's a very grand proposal, sure enough, but who do you think you're engaging with, and who's going to respond to speak for anyone else?

[GrantRobertson]

I do not know if you are aware of the professionally produced FreeCAD Manual written by Yorik : https://yorikvanhavre.gitbooks.io/a-fre ... l/content/
I am sure it will be of great help to you if you are just beginning FreeCAD although it does need an update for Version 0.17/0.18.

Yes, I have seen it. I know I am likely to ruffle a few feathers by saying this, but that "manual" reads more like a very long, detailed list of features than an actual manual. The examples seem to be more of a quick example of what "can be done" rather than a full explanation of how to do things. A real manual doesn't just list one way to do something. It lists all the ways to do a thing, explains the differences between them, explains how to choose between them, and thoroughly explains the implications of choosing one method over the other. For instance, almost all the documentation I have seen tells people to create sketches which are attached directly to the face of a body, without even mentioning that, if you move that face, the sketch will break and the subsequent pad or pocket will disappear.

In my philosophy, the purpose of writing is to convey information. Not just to fill a page. If you fill a page without conveying useful information, then you have done the reader a disservice.

Finally, that document is out of date. Version 0.17 has significant changes that really deserve good documentation.

There is also this book available on Amazon of which you may not be aware: FreeCAD-How-To by Daniel Falck which is, however, sadly out of date.

I did not even imagine that someone would be able to sell a book about FreeCAD. However, as you say, it is very out of date. Especially considering the significant changes in 0.17. Though I have not seen this particular book, I have not been very impressed with the quality of books I have seen from PACKT Publishing. They do lots of formatting tricks to make a book look professionally published, with reviewers and everything, but then most of the content is just words filling pages. And this book is only 68 pages, all total. Only 52 pages of actual text. That's not even enough room for a decent chapter. So, as with almost every other book I have seen from PACKT, it is more of a cash grab than anything else.

IMHO CAD is best learned by practice, practice, practice. Most of the new users who have trouble do so not because of a lack of serious documentation but simply because they do not spend the necessary time to become proficient with the basics. They usually try to jump in with complex models right from the start instead of learning properly by first creating 100's of simple models that slowly progress through all of the tools that FreeCAD offers. I have also had the same experience with FEA and CFD users.

While that is all well and good for someone who wants to work as a professional drafter, regular people are not going to put in that time just to learn a program that is only supposed to be a tool to help them accomplish their true goal (that camper or new kitchen cabinet). Especially if the documentation doesn't help them at all. And they really shouldn't have to. Good documentation can make learning a good program a joy rather than a chore. Good documentation can make it easy for people to get started and then provide a solid reference for when they step out of their comfort zone. And, while I appreciate the number of hours you devoted to your craft, I'm hoping that you would like to spare others from that, if possible, rather than insist they "either put in the work or stay out of the club" as so many seem to do.

[GrantRobertson]

I would really like to see one document:
1) FreeCad for Beginners.

This way the volunteers here wouldn't have to waste hours and hours of their lives answering the same questions over and over. I felt bad when I started so I try to help out some by answering questions if I can. I think just about every question on usage has been asked and answered many times over.

Naturally, that is where one would start. I agree. I too have spent hours and hours answering questions that should have been covered in the documentation. In fact, that is how I learned technical writing. I was on bulletin boards before the Internet, then I participated in Internet newsgroups, and now forums. It seems, as forums have become more popular and easier to set up, even commercial software developers have begun to use them as a crutch, rather than write good documentation. I am a firm believer that the best way to reduce technical support costs is good documentation. And the second best way to increase the popularity of an open-source project is good documentation. (Of course, that comes after writing good software.)

I think just about every question on usage has been asked and answered many times over. That might be your best resource, review the last 5000 comments in the Help section.

Though, that is part of the plan, it seems a lot of people's answers in the forum assume that the questioner has a lot more knowledge that is evidenced by their question. Part of what makes me a better technical writer is that I remember what it was like to not know the thing.

I don't think a book can be finished until Assembly is included, it's hard to document something that's not complete.

Well, I don't expect to finish this thing any time soon. This is a side, side, side project. So it will likely take over a year. In that time the next version may come out. In which case, I will incorporate the new features. I am also well aware that lots of addons are constantly being written. I will do my best to keep of with those as well. Although, after finishing the main part of the manual.

I know of at least 5 Solidworks books with thick dust sitting on them. Learning CAD is like learning to ride a Dirt Bike or Skiing, it turns into an artform in your mind, we don't pick up a manual until we run out of technique and patience. :)

I would venture to guess that they aren't really good books. Books that merely tell you how to use each individual feature without leading you through how all those features work together (the bulk of all technical books) tend to just sit on shelves collecting dust. Books that lead you on a journey of learning do not.

[bejant]

A real manual doesn't just list one way to do something. It lists all the ways to do a thing, explains the differences between them, explains how to choose between them, and thoroughly explains the implications of choosing one method over the other.

Are you going address some of the WorkBenches, or are are you going to include all of them? Either way, to me it seems that you will have a significant amount of work ahead of you. chrisb started writing a document explaining Sketcher and there is a lot of material to cover. The wiki is pretty detailed but things can be hard to find inside it and despite the efforts of the wiki contributors it never seems to be completely up to date. I have to wonder if, instead of writing a separate off-site document, we should instead focus on improving the FreeCAD wiki. For me a problem in updating the wiki is that it is cumbersome and making a document in LibreOffice is much easier. But that's only my experience (or lack of it) so I don't mean to discourage you from writing a new manual.

For instance, almost all the documentation I have seen tells people to create sketches which are attached directly to the face of a body, without even mentioning that, if you move that face, the sketch will break and the subsequent pad or pocket will disappear.

Yes, in Part Design attaching a Sketch directly to a face was the work flow (until 0.17 was released). Now Mapping a Sketch directly to a face of the solid should be avoided.

Finally, that document is out of date. Version 0.17 has significant changes that really deserve good documentation.

That's the thing - for a lot of potential authors it didn't make sense to spend the time and effort in making tutorials or writings while knowing that those documents (or videos) would immediately become obsolete once 0.17 is released. So now a lot of what is available is outdated, and now is probably a good time to write some documentation. Assembly could be added to the document later.


It will be interesting to see what you come up with...

[GrantRobertson]

Are you going address some of the WorkBenches, or are are you going to include all of them? Either way, to me it seems that you will have a significant amount of work ahead of you.

Long Term Goal: Cover the whole damned thing.

Short Term Goal: A decent Beginner's Guide that gets people started, helps them avoid the pitfalls, and answers most of the questions that cause them to constantly ask the same questions over and over again in the forum.

Slightly Less Short Term Goal: Cover all aspects of the parameterized nature of FreeCAD. I feel this is its greatest strength but is also needlessly confusing to beginners. I feel I can make a real contribution to making that more accessible.

I have been looking for a big writing project that can keep my interest without being so huge that it would be impossible. Believe it or not, a 500-page book would be about right. The hardest part is always getting access to the information. Lots of open-source projects say they want help with their documentation, but then never answer any questions other than the standard "how do you do X?" where X is something that gets asked every day.

I have tried contributing to Wikis, but I am always stuck within their poor organization and subject to the whims of other people re-editing what I have written. It may sound egotistical but, if those other people were good writers, I wouldn't need to contribute to their Wiki. For me, it is always better to start from scratch. At first, I will just produce a separate .PDF. As I progress, I will work on learning how to make that available in an online format. Possibly in Wiki form, though I am not partial to the Wiki format. Remember, "Wiki" means "fast." Usually, the rule is: "Fast or good. Choose one."