I mean, they may not have as much as you want, but they do appear to have documentation.
That has a manual in two ebook formats, PDF, and a French and Italian translation.
It has three help sections on the wiki, for each of users, power users, and developers.
And it apparently has some in-application help functionality.
And there’s a help forum.
EDIT: It also looks like some people have written books about using FreeCAD.
They have what looks like documentation. That manual is out of date and incomplete.
FreeCAD exposes a Python console as an end-user feature. It has a macro recording system for automating repetitive tasks, much like MS Office does, it uses Python as a scripting language. Can you show me an API reference for this feature?
I want to write a macro that will insert some text into the cell of a spreadsheet I have selected. Click a cell, click the macro button, and it puts some text into that cell. It can do this. There are macros published that do this kind of thing. Show me where in their published documentation the functions necessary to do that are described.
They don’t help people in that forum. For some reason, FreeCAD’s forums default to English, but no one in the community speaks English as a first langauge. So you ask a detailed technical question, and some French guy babelfishes a couple of the key words and posts a random paragraph about the workbench you mentioned and a random unrelated code snippet. I’ve paid to have someone help me work on this software, that went nowhere.
FreeCAD exposes a Python console as an end-user feature. It has a macro recording system for automating repetitive tasks, much like MS Office does, it uses Python as a scripting language. Can you show me an API reference for this feature?
kagis
https://freecad.github.io/SourceDoc/modules.html
I want to write a macro that will insert some text into the cell of a spreadsheet I have selected. Click a cell, click the macro button, and it puts some text into that cell. It can do this. There are macros published that do this kind of thing. Show me where in their published documentation the functions necessary to do that are described.
I don’t use FreeCAD, don’t have any familiarity with this spreadsheet functionality, but let’s look.
kagis
They appear to have a Doxygen API reference for their spreadsheets here:
https://freecad.github.io/SourceDoc/d0/da8/classSpreadsheet_1_1Sheet.html
setCell()looks like it sets a cell value to me.That appears to take a CellAddress, which it looks like is obtained via
getCellAddress(). As I said, I haven’t used FreeCAD’s spreadsheets, but I expect that it has some cell-addressing syntax akin to spreadsheets that I’ve used, and that one passes the name in to that, same as one would if referencing the cell in a formula to compute another cell’s value. I’ve no idea if FreeCAD’s syntax is the same as Excel’s, or if it differs, though, and I’m not going to look that up; that shouldn’t be an API-specific issue.It also looks like it has a macro-recording feature. It looks like, to my quick skim, that natively generates Python:
https://wiki.freecad.org/Macros
You can also directly copy/paste python code into a macro, without recording GUI action.
And looking at the source of an arbitrarily-chosen macro, it appears to be in Python, rather than some app-specific macro language:
https://wiki.freecad.org/Macro_Rotate_View
So I expect that you can most-likely just record yourself performing the operation and the macro-recording functionality will give you the code without you needing to write something.
EDIT: It sounds like you want to get the selected cells rather than specifying the to-be-modified cell by name, which it looks like
SheetTableView::selectedRanges()provides you with; Range objects appear to provide for a selection including many cells, but if you only want, say, the starting cell (which would presumably be the case for a single cell selection), then it looks likeRange::from()provides that, since the starting cell would be the same cell as the only cell in a selection if there’s a single-cell selection. That returns a CellAddress as well.
Either donate or write the documentation yourself, complaining about unpaid FOSS devs and maintainers doesn’t do anything
Once again, “I don’t understand this, I guess it’s up to me to explain how it works.”
I didn’t go to software engineering school. I went to flight school. Reading and understanding the source code of an application as large and complex as FreeCAD is outside my skillset.
I’m a flight instructor. I can and have taken people from never having flown a plane before to licensed pilot. You want me to teach flight school, you’ve got to give me the plane’s POH. It is not my job to write the Pilot’s Operating Handbook. It is my responsibility to teach students how to read it.
You get me good documentation for this software I’ll create and publish a course on parametric furniture design. But I’m not going to sift through source code trying to figure out how to write a macro any more than I’m going to pull the panels off a Cessna and trace wires to figure out what the switches do. That is the responsibility of the people who made the damn thing.
Maybe a commercial offering would be a better choice for you.
The only other package even remotely compatible with Linux is OnShape and their licensing terms are a non-starter. Frankly so are AutoDesk’s.
Then donate money to the project
I’m pretty sure I can demonstrate that doesn’t work; people have donated more money to the project than I’m capable of giving alone and that didn’t bring about usable documentation. The definition of insanity is watching other people fail and then doing exactly what they did.
I’m sorry you’ve had a poor experience with FOSS software, I’m sure the project will give you a full refund if you ask them.
You know what? That’s okay, I’ll just switch operating systems to Microsoft Windows or Apple MacOS and start using Autodesk Fusion360, paying hundreds if not thousands of dollars on a recurring basis to at least two American corporations that directly support the rise of fascism. I’ll be directly financially supporting everything from AI slop to the abduction of academics in broad daylight but just think of the fives of minutes I’ll save over the next decade drafting cabinets.
Unethical pro tip: write obviously wrong documentation, post it somewhere, and then wait for people to flame you while explaining the correct methods.
I’m ashamed to admit I’ve done that a couple of times when I was completly ignored for straight up asking how to do something.
Murphy’s Law: the best way to get the right answer on the internet is not to ask a question; it’s to post the wrong answer
This is the fastest and bestest way. And this is the reason Wikipedia works lol
Do it as an end user? Be part of the solution?
Documentation is one of the many ways to contribute that don’t involve coding.
“I don’t know how this works. I guess I’ll have to be the one to explain it.”
“I don’t know how this works. I guess I’ll have to be the one to explain it.”
Nope, it should read: “I don’t understand how it works. It probably means I should (make the effort to) learn how to use it, and then I may want to share what I learned to make it easier to others.” And then, yeah, you’re right:
Okay, how much effort should an end user be expected to put into learning how to use software? The standard used to be RTFM. Oh us Linux users get bitched at when we tell people to RTFM.
Well I Read The Fucking Manual. The macro scripting API isn’t anywhere in The Fucking Manual. You ask how you’re supposed to learn how to use a feature that isn’t in The Fucking Manual, and you get asked why you haven’t Written The Fucking Manual.
You’re told “The Python console has a help feature. Type help() to enter the help mode.” Yeah, that’s a standard feature, here’s the thing: It’s broken in FreeCAD. If you type anything at the help prompt, it exits the help system. You can’t get a list of modules to browse it that way. So you have to know the name of the module that the function you’re looking for is in. Somehow.
I think it’s somewhere around this point that the end user has done what tehy reasonably should have and the ball is in the developer’s court. There is a difference between “Hey it would be great if you guys could help us flesh out the tutorial section on our website a bit!” and “We outright refuse to document our scripting API in any way, if the busted automated help system isn’t good enough, you write it.”
I’m not Writing Their Fucking Manual for them. That is utterly insane.
Okay, how much effort should an end user be expected to put into learning how to use software?
As much as they’re need to, as much as they’re willing to.
If you need to use the software, then also you need to learn how to (properly) use it. If it’s too much work because of the poor doc or because it’s just something hard to use for you (which could very well be, I don’t know but I do know I’ve failed myself to learn to use Emacs save that I don’t blame the devs or the docs that’s provided for free), then you need to either:
- Spend some more time (to learn it better).
- Spend some money to have someone make some digest version of a too technical doc that will help you. I decided not to do that with Emacs because I realized I could also not use the software and still be able to do my work fine.
- Find another app that will suit your needs better and time/energy availability.
FLOSS is provided as is. The user is free to use it however they fancy (which is amazing) but as a user we’re entitled to no support either. And why would we?
I’m not Writing Their Fucking Manual for them. That is utterly insane.
No one is asking you to write the doc if you don’t feel like it, and that’s 100% fine: no one will ever blame you for not writing it either. I’m just telling you that if you think it’s too much work for you you should not expect anyone to do it for you either. End of the story.
But let me ask you this: would writing the manual really be that much more insane than, say, writing the hundreds of thousans of lines of code to make the application itself? And if you think it would be more work to write the doc than to create the app (and offer it for free) may I ask you why? It’s a real question, as I hope you realize I’m not trolling I’m just curious to understand your reasoning.
BTW, I’m no dev, I’m a mere (and non expert) user of FLOSS myself. So, I know quite well how frustrating docs can be ;)
The good thing about OSS is you don’t have to be a programmer to contribute.
If the documentation is lacking you can write up a one pager and submit it to their wiki for integration.
https://wiki.freecad.org/User_hubHow am I supposed to write the documentation for software that I have no method of learning how to use?
Read the wiki, experiment, and improve it.
But indeed, CAD is a very specific way of thinking, and if you haven’t done any technical drawing course you won’t find it by yourself
You want to play a fun puzzle game? Go figure out how to get basically anything done with the macro/scripting system. The app exposes a Python console to the user and they didn’t bother to publish an API reference so you’re left resorting to the “dangle a cat from a string and hit it with a stick to see what falls out” method of veterinary school. Why is being open source an accepted excuse to force users to attend Pinata University?
This is what I tell my co-workers:
Don’t come to me with a question and ask for the answer. Come to me with the answer that you came up with and ask me why it doesn’t work.
In other words, at least try to be the solution. You’re more likely to get help from those who can help you.
Start writing the documentation. Fill in everything you know. There might be people you help who don’t know as much as you.
Post about it, and give others the opportunity to correct your documentation.
Open the source code and see if you can start to work out the API. It’s all in there. That’s where the people who are writing it are documenting it.
If you put the effort in, then you’ve joined the team, even if no one invited you. Once you’re on the team, the people writing the code will see you as a contributor and they’ll be more willing to put the time in to help you.
Okay, let me ask you this: Why would the developers of FreeCAD demand their documentation be that inefficient and poor quality?
I mean, we’ve got two options here:
Option A: The developers of the software, the people who already know how to program at the application level, who are already familiar with at least some of the codebase, could write down what all the features are and what they do. Armed with that basic documentation, power users, folks who are specialists in using this class of software for its intended purpose, can create tutorials and coursework to teach people how to make projects in it, or create and share useful macros and extensions and whatnot, building the ecosystem, of our app specifically and FOSS software in general…OR
Option B. We can get weirdly pissy about it and insist that those end users, people who don’t have a need in their lives to know how to write software applications but do have a need in their lives to use mechanical engineering software, to gain enough proficiency in not one but two programming languages to examine the source code to figure out how it works and write the documentation themselves. The best case scenario here is it wastes a whole lot of manpower of competent coders who now have to read and familiarize themselves with someone else’s codebase. Meanwhile, a lot of smaller contributions that end users would have made get abandoned because the support they need to do that deliberately doesn’t exist. So adoption of our app specifically and of FOSS in general chills, we continue to maintain FOSS’ reputation as unusable garbage made by damaged nerds, and the people will continue to say “I would switch to Linux but I need functioning CAD software for my job/hobby so I’m going to have to keep making large recurring payments to corporations like Microsoft and Autodesk who directly support the rise of fascism in the West.”
OPTION FUCKING B IT IS.
By watching YouTube tutorials or turning on the monkey part of our brains and poking around in the software until something happens.
Pay them?
How do we get the makers of FreeCAD to document their fucking software?
It’s FLOSS. You may not like that but it’s up to everyone of us to contribute to make things better. With our time, with our money, or with our expertise. And there is no fucking need to be fucking mad at anyone for not fucking doing it for you.
Or you can spend the money, time and expertise you don’t have for FLOSS on shiny Apple or Microsoft proprietary apps so they can keep on not making good documentation and not giving a fuck about it. It’s fucking up to you.
It’s an open source project, you dig into it a bit and issue a pull request with the documentation.
Why the fuck should an end user of mechanical engineering software know how to use Git? Does Blender leave entire features completely undocumented expecting their audience of 3D animators to write their APIs for them given nothing but the app’s source code? Does GIMP? Does KDENLIVE? Does Arch Linux? Hell no, Arch has a massive and detailed wiki. Imagine if there just was no documentation for how to script in Bash and the Arch devs were like “Oh yeah think you could write that for us? You know, while you’re trying to get something fairly basic done?”
