Troubleshooting Page

[patn]

Discussion in another thread brought up that a troubleshooting page would be good to cover general errors like the part turning black to reduce repetition on multiple command pages. I think a link on the https://www.freecadweb.org/wiki/User_hub would be good. The format would be something like:

• error description
• short error explanation
• solution/workaround

Any thoughts?

[chrisb]

We can give it a try but it is not an easy task. Based on the questions in the forum we have created a now a bit outdated page: https://forum.freecadweb.org/viewtopic. ... 64#p170906 .

[triplus]

Hi @patn.

In general the idea is good. What is usually missing is somebody creating such list and maintaining it. In addition FreeCAD project, being big and having a lot of users, that results in plethora of issues and questions, each being slightly different. "Troubleshooting Page" therefore can help up to a point, but majority of support still needs to happen on individual level.

[vocx]

Discussion in another thread brought up that a troubleshooting page would be good to cover general errors like the part turning black to reduce repetition on multiple command pages. I think a link on the https://www.freecadweb.org/wiki/User_hub would be good. The format would be something like:

• error description
• short error explanation
• solution/workaround

Any thoughts?

There is already a FAQ in the wiki https://www.freecadweb.org/wiki/FAQ

It just needs to be updated and maintained. I feel what would make sense is to create FAQs for specific topics of FreeCAD, like one for part modelling, another for 2D drafting, another for FEM, another for architectural design, etc. Breaking the FAQ into sections makes it easier to handle.

[NormandC]

Thanks for creating the topic patn.

I feel what would make sense is to create FAQs for specific topics of FreeCAD, like one for part modelling

Actually, the FAQ page barely contains stuff about modeling issues, section 4 has only 3 topics.

Some issues may be specific, but a general Troubleshooting models page (empty page for now!) would be useful: many issues are caused by the OCC kernel or how FreeCAD links to it, they are not workbench-specific. They are issues that we have been endlessly repeating here on the forum, so it would be a real time saver to have a page to link to.

I started to take some notes about what this troubleshooting page may contain, pasting them here. Still not sure how to present the info. I guess it needs to start with some variant of "Why does this happen in my model?".

• The model turns black
• Issues caused by non-manifold models, OCC does not prevent their creation.
• Pad creates a pocket, and Pocket creates a pad: inverted model after an operation such as a refine shape feature https://forum.freecadweb.org/viewtopic.php?f=3&t=32664
• Boolean issues with co-planar and tangent faces
• Fillet and chamfer limitations
• Single contiguous solid rule in PartDesign

Each topic should explain why it happens, and how to fix it. They should also contain images that show the issues.

[NormandC]

I think a link on the https://www.freecadweb.org/wiki/User_hub would be good.

Sure, and I suggest to also add it to the Online_Help_Toc, maybe right after Tutorials.

[patn]

I think this will be easier to talk about with a rough draft so I created https://www.freecadweb.org/wiki/Troubleshooting_models and threw in a couple examples. I haven't linked the page anywhere yet.

This is an example of the content with some basic format like an FAQ. It will probably need more formatting if it grows larger.

As @NormandC, said this page would be the landing spot for general errors that impact multiple commands up to whole workbenches or the entirety of FreeCAD.

@vocx You may be right that some of the lower level information like part design workbench requiring a contiguous solid should be routed into the FAQ. The FAQ is only supposed to answer common questions though: "This page attempts to answer the most common questions asked on the FreeCAD forums."

[patn]

I've made some more updates to this page.

I don't intend for every OCC error code to be listed, but I added ones that I kept hitting while trying to do some surfacing type modeling.