Working on the documentation (was: Arch Window - Glass Panel Area etc in Python Script?)

Post here if you have a FreeCAD-related job to offer to the FreeCAD community. This can include programming or modeling.
vocx
Posts: 1906
Joined: Thu Oct 18, 2018 9:18 pm

Working on the documentation (was: Arch Window - Glass Panel Area etc in Python Script?)

Postby vocx » Thu Oct 25, 2018 7:50 pm

yorik wrote:
Thu Oct 25, 2018 2:52 pm
vocx wrote:
Wed Oct 24, 2018 9:52 pm
Ehem. Can I get some coin?
Why not, actually? If you are serious about this, would you mind writing a small "project", like, describe what you would do with money, and how much you would want? This would be a perfect case to do a test with allocating money from the bountysource.
Well, I'm currently, ahem, between jobs, so I could dedicate all my time to documenting FreeCAD.
I just need money for myself; here are my estimates:
  • USD 100 for underwear, new jeans, and maybe a pair of comfy trousers
  • USD 100 for teeth cleaning and two fillings
  • USD 100 for a case of imported German beer
  • USD 100 per week; 14 hours per day, 7 days per week; every Arch function documented, and maybe a few tutorials on how to use the things, like the topic of Door and Window opening
So, basically, if you give me USD 1000, I could spend the months of November and December doing documentation on the wiki for everything that you need. I could also look into usability features, like I've been doing on the forum, and look into the Python code. For example, is there a particular reason why Python code is not documented at all? No Docstrings in the source?
vocx wrote:
Wed Oct 24, 2018 10:37 pm
In order for an Arch Window to be positioned well, you should use the Draft Snap toolbar with the Draft Near method.
Actually you can now use all the snap tools. As soon as you hover the mouse over a face, the window will take the face orientation. After that, you can snap anywhere, to the middle of an edge, etc. If you use the "Sill height" parameter, you can actually snap on the baseline of the wall and have it placed at a correct location. If you don't have the near snap activated, however, indeed you have the risk to snap outside of the wall face.

Maybe we should always activate near snap by default when placing a window?

Indeed this is all still far from perfect... But I still fail to see how to reach a good, ideal, perfect workflow to place a window in a wall...
What you are describing is already possible? Or is it part of a new commit? I started my model many months ago, placed Windows and Doors once, and that was it, so I haven't tried all the snapping options lately. I could investigate and document this better.
paullee
Posts: 1840
Joined: Wed May 04, 2016 3:58 pm

Re: Arch Window - Glass Panel Area etc in Python Script?

Postby paullee » Thu Oct 25, 2018 10:56 pm

vocx wrote:
Thu Oct 25, 2018 7:50 pm
... look into the Python code. For example, is there a particular reason why Python code is not documented at all? No Docstrings in the source?
Lot of questions indeed :)

Incomplete Arch Wiki Pages https://forum.freecadweb.org/viewtopic.php?f=23&t=31472

FreeCAD Objects - isDerivedFrom("Part::Feature")...? https://forum.freecadweb.org/viewtopic.php?f=22&t=31500

ArchWall basewires, getExtrusionData() ... issues https://forum.freecadweb.org/viewtopic. ... 57#p261324

Hope something can be done
User avatar
yorik
Site Admin
Posts: 11585
Joined: Tue Feb 17, 2009 9:16 pm
Location: São Paulo, Brazil
Contact:

Re: Working on the documentation (was: Arch Window - Glass Panel Area etc in Python Script?)

Postby yorik » Fri Oct 26, 2018 4:50 pm

Okay I split this thread so we can start a specific discussion about this.

Basically, you are proposing to use all the money we have in the box. I'll check how much we really have now, it might have changed. In any case, I'm not against it at all, I actually think spending that money on documentation would be a very good way to spend it. However, I think we need more people than just myself to decide.

I also think you should do a more detailed "plan", that is, (like you started already), identify topics you think you could work on, and put some goals, like, in XX weeks you plan to have done X and Y, etc. I don't doubt that with a good plan the vast majority of people here will agree to fund you.

In any case:
vocx wrote:
Thu Oct 25, 2018 7:50 pm
is there a particular reason why Python code is not documented at all? No Docstrings in the source?
The python code in FreeCAD might not be the best in the world, but it is far from "not documented at all". What are you referring to?
vocx
Posts: 1906
Joined: Thu Oct 18, 2018 9:18 pm

Re: Working on the documentation (was: Arch Window - Glass Panel Area etc in Python Script?)

Postby vocx » Fri Oct 26, 2018 5:32 pm

yorik wrote:
Fri Oct 26, 2018 4:50 pm
Okay I split this thread so we can start a specific discussion about this.

Basically, you are proposing to use all the money we have in the box. I'll check how much we really have now, it might have changed. In any case, I'm not against it at all, I actually think spending that money on documentation would be a very good way to spend it. However, I think we need more people than just myself to decide.
Okay, I'll get serious. I definitely don't want consume every single dollar of the FreeCAD project if there are more pressing issues. For example, I'd rather you spend that amount paying a good C++ developer to improve a core component (PartDesign, Sketcher, OCCT?).

With that said, yes, I could spend my full time documenting FreeCAD, if the core developers consider that a priority.
I also think you should do a more detailed "plan", that is, (like you started already), identify topics you think you could work on, and put some goals, like, in XX weeks you plan to have done X and Y, etc. I don't doubt that with a good plan the vast majority of people here will agree to fund you.
Understood. I'll try writing a few things here.

In particular, I am not a very experienced C++ programmer, so I have a hard time recognizing what the functions are supposed to do, or where the definitions are, what they are supposed to modify, return, and all that. I'm much more comfortable with Python, so I thought, I could look into the code of Draft and Arch, mostly python files and in that way figure out how they work, and then document that on the Wiki.

Of course, step-by-tutorials to show how the tools work, like I do in the forum, is the simplest thing because then I don't have to mess with the code, just describe how to use the tools, with some pictures. I'd try to cross-reference as many pages as possible so that the documentation is easily accessible.

But again, what is the priority? Is a particular workbench a priority? I'd focus mostly on Arch and Draft because they are easy to use, and I have experience with them. But if asked, I could also devote my time to support another workbench that is in need of documentation, Part, PartDesign, FEM, etc., you name it.
In any case:
vocx wrote:
Thu Oct 25, 2018 7:50 pm
is there a particular reason why Python code is not documented at all? No Docstrings in the source?
The python code in FreeCAD might not be the best in the world, but it is far from "not documented at all". What are you referring to?
I was exaggerating a bit. As I was looking at Mod/Arch/ArchSectionPlane.py and I thought that there were many functions with no Docstrings, that is, the '''Explanation below a function definition'''. However, most of those functions are trivial, so I don't think they really need long descriptions. Still, I'd say it's good practice to add Docstrings and more comments. I feel Mod/Draft/Draft.py is better commented, so I'd try to replicate that with the Arch code.

You mentioned in the other thread about automated creation of API documentation. I believe this is precisely what Sphinx does http://www.sphinx-doc.org/en/master/usa ... start.html but I'm not sure if you have considered that at all. Is Doxygen mostly for C++?
yorik wrote:
Fri Oct 26, 2018 2:09 pm
We have actually a problem here: The API wiki pages are created manually, and yes, indeed they are almost all out of sync with current version. On the other hand, we have the doxygen auto-generated pages ...
I believe Sphinx is the solution when documenting Python interfaces, and it's the tool used in projects such as Numpy, Matplotlib, Scipy, etc., which have pretty good documentation. For Sphinx to work, I believe most functions in the code itself need to be well commented, even if a bit verbose.
Last edited by vocx on Sat Oct 27, 2018 6:54 pm, edited 1 time in total.
paullee
Posts: 1840
Joined: Wed May 04, 2016 3:58 pm

Re: Working on the documentation (was: Arch Window - Glass Panel Area etc in Python Script?)

Postby paullee » Fri Oct 26, 2018 8:32 pm

Below post on original thread is meant as a response, or it can't be understood :)

https://forum.freecadweb.org/viewtopic. ... 20#p264683
User avatar
yorik
Site Admin
Posts: 11585
Joined: Tue Feb 17, 2009 9:16 pm
Location: São Paulo, Brazil
Contact:

Re: Working on the documentation (was: Arch Window - Glass Panel Area etc in Python Script?)

Postby yorik » Sat Oct 27, 2018 6:24 pm

vocx wrote:
Fri Oct 26, 2018 5:32 pm
I was exaggerating a bit. As I was looking at Mod/Arch/ArchSectionPlane.py and I thought that there were many functions with no Docstrings, that is, the '''Explation below a function definition'''. However, most of those functions are trivial, so I don't think they really need long descriptions. Still, I'd say it's good practice to add Docstrings and more comments. I feel Mod/Draft/Draft.py is better commented, so I'd try to replicate that with the Arch code.
Perfect. This kind of things is indeed very useful.
vocx wrote:
Fri Oct 26, 2018 5:32 pm
I believe Sphinx is the solution when documenting Python interfaces, and it's the tool used in projects such as Numpy, Matplotlib, Scipy, etc., which have pretty good documentation. For Sphinx to work, I believe most functions in the code itself need to be well commented, even if a bit verbose.
We tried using sphynx already (everything is still there in src/Doc). But in FreeCAD we have a lot of Python functionality that is not coded in python, but generated by C++ code, sometimes even at runtime. And it turns out sphynx is pretty bad at finding and documenting these.

On the other hand, it also turns out that doxygen can do a job almost as good as sphynx to document python code. The only real difference is that the html result of doxygen is not so elegant than sphynx, but that can be addressed outside, with css theming/formatting for example. So probably our time is much better spent trying to use only one doc system instead of several different ones...

BTW, I just checked now, we have about USD 1900 in our bountysource. So this makes your proposal much more valid and interesting, as there would still be money for other things.
vocx
Posts: 1906
Joined: Thu Oct 18, 2018 9:18 pm

Re: Working on the documentation (was: Arch Window - Glass Panel Area etc in Python Script?)

Postby vocx » Tue Oct 30, 2018 12:29 am

yorik wrote:
Fri Oct 26, 2018 4:50 pm
I also think you should do a more detailed "plan", that is, (like you started already), identify topics you think you could work on, and put some goals, like, in XX weeks you plan to have done X and Y, etc. I don't doubt that with a good plan the vast majority of people here will agree to fund you.
I basically spent two full days looking into the wiki and documentation to see how it all worked, so this is my proposal.

1. I feel there are two needs, (1) documenting the usage of FreeCAD, and (2) documenting the programming aspects of FreeCAD, either for advanced users (scripting) or for developers. What is more important? Or what is a pressing matter?

2. I feel I could dedicate myself full time to the first task (1) documenting the usage of FreeCAD, particularly the most used workbenches like Arch, Draft, Part, PartDesign, Sketcher, and TechDraw. I would look into the main page of each, say, https://www.freecadweb.org/wiki/Arch_Module, look into every single tool, for example, https://www.freecadweb.org/wiki/Arch_Wall, and add or improve the information there. A big portion of the job would be to add links to relevant and useful pages. That is, add links to Draft Wire, Draft Line, etc., if mentioned in other pages. This will help with making the wiki more user friendly, because it would be possible to jump to different tools quickly.

3. Navigation tools are needed. As was noted in the other thread https://forum.freecadweb.org/viewtopic.php?f=21&t=31876 I think navigation boxes are useful, because they help you go to the specific workbench that you want fast. Ideally, every workbench should have a navigation box with the tools inside of it, so that if you are looking at the Arch Workbench, you can immediately jump to other tools inside that same workbench, without going back to the main page of that workbench.

4. Translations are important. It is not my objective to complicate the translation effort of the software. As was mentioned in another thread, using templates a lot would mean creating a translated template for each language which is cumbersome. https://forum.freecadweb.org/viewtopic. ... 17#p265217 I believe this shouldn't be too complicated for simple templates, as there are around 20 main languages for which makes sense to have translations. Of course, speakers of other languages should do the work to maintain their own languages when it cannot be quickly automated.

I believe the more successful a project is, the better it is at receiving translations. So let's make sure the project has good documentation and then we'll see an increase in popularity, and then surely it will get a lot of translations.

5. Physical documentation and printing. I am not sure how good the PDF version of the documentation is. Is this created entirely from the wiki? A wiki guideline says that there shouldn't be too many repeated information because then printed documentation would have the same information repeated many times. https://www.freecadweb.org/wiki/WikiPag ... Guidelines

This is something that worries me if using navigation boxes, as I expressed in point 3 above. Are navigation boxes also included in the documentation? I wouldn't like this in a printed document, but I like it in the online version.

6. I am not sure what to do with the application programming interface documentation, C++ and Python APIs. Is this supposed to be generated automatically with Doxygen and placed in https://www.freecadweb.org/api ? Then why does it appear as well in the wiki? Was the API documentation in the wiki placed there manually, before Doxygen was implemented? If this is the case, I believe we should use only one place to put this information. Remove the information in the wiki, and use only Doxygen, or the other way around.

This thread sheds some light on the matter https://forum.freecadweb.org/viewtopic.php?f=21&t=31824

This is on the wiki https://www.freecadweb.org/wiki/Category:API
This section contains obsolete data, and is in the process of being transferred to autogenerated API documentation on http://www.freecadweb.org/api
In the wiki, I modified and introduced a couple of templates that make looking at the API better on the eyes. See for example, https://www.freecadweb.org/wiki/Draft_API for functions, and https://www.freecadweb.org/wiki/Base_API for classes, and https://www.freecadweb.org/wiki/Object_API for properties.

The templates are
https://www.freecadweb.org/wiki/Template:APIFunction function with description, and return value
https://www.freecadweb.org/wiki/Template:APIFunction_b function without description, nor return value
https://www.freecadweb.org/wiki/Template:APIClass class with description
https://www.freecadweb.org/wiki/Template:APIClass_b class without description
https://www.freecadweb.org/wiki/Template:APIProperty property

But still I don't want to touch this more because I don't want to do duplicate work if you are actually in the process of building much better documentation using Doxygen.

On the other hand, a simple scripting guideline to use a tool is documented in the tool itself, for example, look at Draft Line https://www.freecadweb.org/wiki/Draft_Line The command (makeLine) is documented there. The same function signature is in https://www.freecadweb.org/wiki/Draft_API

Having two points with the same information should be avoided. Should the first page (description of the tool) direct to the API? Should the API have examples at all? Or only a listing of the functions available? They should have links to each other, which is exactly what wandererfan did with the TechDraw API pages, he put links back to the user documentation. https://www.freecadweb.org/wiki/TechDraw_API

But at the same time, wandererfan put examples in the API section. Most of those functions are strictly programming functions that can't be used from the GUI, so that's the reason they aren't described in the user documentation. But others like https://www.freecadweb.org/wiki/TechDraw_SaveSVG are described in both.

What I would do is describe the tool in the tool page itself (say, Draft Line) and also add a link to the API page, both the wiki and the Doxygen generated site (https://www.freecadweb.org/api).

By the way, the APIFunction templates that I mentioned above are okay for C++, but aren't okay for Python, because in Python you typically specify the default arguments with an equals sign as described here https://www.freecadweb.org/wiki/Python This equals sign breaks the wiki's {{template}} system which does substitution of parameters with that sign.

7. Fix page naming. I suppose in the past workbenches were called "modules". All workbench links actually point to a page with _Module in the name. And I guess all redirections redirect to these. This is confusing to the user, so they should go to https://www.freecadweb.org/wiki/Draft_Workbench, without being redirected to https://www.freecadweb.org/wiki/Draft_Module

Would this be a titanic task? Would it break translations? Translated pages could be copied and pasted into a new correctly named workbench. But the current translation system doesn't allow direct edits, so I'm not sure about this.

8. Fix tool page naming. I think each tool should be named in a reasonable manner, like [Workbench]_[Tool]. This is included in the Wiki guidelines https://www.freecadweb.org/wiki/WikiPages#Structure In many cases this is respected (Draft Line, Draft Wire), but in others, the name of the page sort of refers to the icon. For example, the tool https://www.freecadweb.org/wiki/TechDraw_NewArch should probably be named "TechDraw_ArchView". Adding "New" to the name is confusing. Obviously it creates a "new" ArchView, but this makes it hard to refer to the tool with the proper name.

"Please check the [[TechDraw NewArch]] tool" works but it sounds strange if I include this in a tutorial.

"Please check the [[TechDraw ArchView]] tool" sounds better, but doesn't work because the page doesn't exist. I could use a redirection, or just rename the original tool page, and change all links that point to it accordingly.

Again, the same problem. Would translations break?

A problem that I see is, again, the repeated information. For example, there exists both https://www.freecadweb.org/wiki/PartDesign_NewSketch and https://www.freecadweb.org/wiki/Sketcher_NewSketch They both refer to essentially the same tool, a Sketch. So, maybe "PartDesign Sketch" should just point to "Sketcher Sketch" (which doesn't exist at the moment).

9. Redirections. I love them. It's a simple way of fixing things and making explanations fluid were it makes sense. But I'm not sure if other wiki administrators are fine with it. I don't think redirections take much space in the server, but my impression from the other thread is they aren't happy if I use too many redirections.

Let's say a tool is strangely named "A". So I create a page with a better name "B", which redirects to "A". All user pages are changed to use "B" (the redirection), instead of "A". Ultimately I move all the information into "B", and delete "A". Would that work? Would translations break?

Okay, so these were my observations. Now with a timeline.

10. Timeline. I think the easiest is to go workbench by workbench.
Week 1: planning stages in forum, organization of tasks
Week 2: document the Draft workbench
Week 3: document the Arch workbench
Week 4: document the TechDraw workbench
Week 5: document the Part workbench
Week 6: document the PartDesign workbench
Week 7: document the Sketcher workbench
Week 8: (week to finish documenting pages that weren't finished on time)
Week 9: revisit the tutorials, update old tutorials, add new tutorials
Week 10: whatever is needed, after feedback in the forums

The first week of planning is what we are doing right now, discussing with the interested parties, and planning, so that when I start editing pages, people are satisfied, and won't protest too much. Of course, if people don't have many comments, I'd just start working on the Draft workbench immediately.

By documenting, I mean clicking on every single link of the workbench, making sure the {{GUICommand}} template is correct, making sure the information is correct and up to date, adding links, fixing broken links and redirections, adding navigation box, adding API code when necessary, cross-referencing the information with the API by Doxygen and github, adding categories to the page, and minor tasks like that. I'll also post in the forum every day to inform everybody about the progress of the documentation, and to get feedback if there is something that users would like to see.

About the tutorials, I could try to recreate and update some tutorials that were created for 0.16 and earlier versions, so that the instructions work with the more recent 0.18 version. I recently finished a new tutorial https://www.freecadweb.org/wiki/Tutoria ... en_windows so part of my experience with the wiki stems from writing that, and finding the links to the workbench tools. I believe by writing tutorials, it becomes immediately apparent which workbench tools require better documentation.

Each week should be paid USD 100. So, after ten weeks, you would have paid USD 1000. Of course, if you are generous, you could put a bit more, as you say there is almost double that in the pot. Personally, I'd like to be paid all at the same time, say, USD 1000, by week 6, so that it makes sense money transfer-wise and so I can fill my taxes accordingly. Of course, this is subject to review. If you think the documentation job is not okay, then we can end the job there.

Of course, this is all in regards to user documentation. Is user documentation a priority over API documentation? Or is API documentation (the source code) more important? Because if that's the case, then I'd have to go into the C++ and Python sources, and that's a bit more of a complex task, which is more of the domain of the core developers, because they are the ones who are able to describe better how each piece of code works. I could try above all correct the docstrings of the Python files sources because that is markedly easier.
User avatar
NormandC
Posts: 18534
Joined: Sat Feb 06, 2010 9:52 pm
Location: Québec, Canada

Re: Working on the documentation (was: Arch Window - Glass Panel Area etc in Python Script?)

Postby NormandC » Tue Oct 30, 2018 4:30 am

vocx wrote:
Tue Oct 30, 2018 12:29 am
7. Fix page naming. I suppose in the past workbenches were called "modules".
No, they are still called modules internally. Actually, the workbench is the GUI side (toolbars) while the module contains both the GUI (workbench) and the python interface. But for better or for worse, we all use either name indifferently.

vocx wrote:
Tue Oct 30, 2018 12:29 am
8. Fix tool page naming. I think each tool should be named in a reasonable manner, like [Workbench]_[Tool]. This is included in the Wiki guidelines https://www.freecadweb.org/wiki/WikiPages#Structure In many cases this is respected (Draft Line, Draft Wire), but in others, the name of the page sort of refers to the icon. For example, the tool https://www.freecadweb.org/wiki/TechDraw_NewArch should probably be named "TechDraw_ArchView". Adding "New" to the name is confusing. Obviously it creates a "new" ArchView, but this makes it hard to refer to the tool with the proper name.
You can't, you'll break the "What's This?" functionality which brings up the offline documentation. Please look it up (Std WhatsThis), the page naming requires to follow the sWhatsThis value for the command in the source code. Please search the Wiki forum, I already mentioned this very recently (sorry don't have time to look for it myself). If you want clearer names you would need to rename thousands of wiki command pages, and thousands of strings in the source code! And as already explained, making redirect pages would break translations.
vocx
Posts: 1906
Joined: Thu Oct 18, 2018 9:18 pm

Re: Working on the documentation (was: Arch Window - Glass Panel Area etc in Python Script?)

Postby vocx » Tue Oct 30, 2018 10:29 pm

NormandC wrote:
Tue Oct 30, 2018 4:30 am
No, they are still called modules internally. Actually, the workbench is the GUI side (toolbars) while the module contains both the GUI (workbench) and the python interface. But for better or for worse, we all use either name indifferently.
Don't you think it's a poor decision to use both names interchangeably? It causes confusion for new users that don't know the history of FreeCAD. It seems to me that everybody in the forum uses "workbench", which is nice if you come from CATIA and other software packages that use that word. I only saw the workbenches being referred to as "modules" in the wiki, which is noticeably showing its age, as it has a lot of old information.

Don't you think we should standardize this more? If the source code defines everything as a "module", then we should use that name everywhere.

Most workbenches on the wiki redirect to the "module" name, but others like https://www.freecadweb.org/wiki/Inspection_Workbench or https://www.freecadweb.org/wiki/Mesh_Workbench are the opposite; the "workbench" name seems to be the main name.

I don't think there is any reason to make a distinction as workbench for the GUI, and module as the entire programming interface, including the GUI. I believe this should be standardized.
vocx wrote:
Tue Oct 30, 2018 12:29 am
8. Fix tool page naming. I think each tool should be named in a reasonable manner, like [Workbench]_[Tool]. This is included in the Wiki guidelines https://www.freecadweb.org/wiki/WikiPages#Structure In many cases this is respected (Draft Line, Draft Wire), but in others, the name of the page sort of refers to the icon. For example, the tool https://www.freecadweb.org/wiki/TechDraw_NewArch should probably be named "TechDraw_ArchView". Adding "New" to the name is confusing. Obviously it creates a "new" ArchView, but this makes it hard to refer to the tool with the proper name.
You can't, you'll break the "What's This?" functionality which brings up the offline documentation. Please look it up (Std WhatsThis), the page naming requires to follow the sWhatsThis value for the command in the source code. Please search the Wiki forum, I already mentioned this very recently (sorry don't have time to look for it myself). If you want clearer names you would need to rename thousands of wiki command pages, and thousands of strings in the source code! And as already explained, making redirect pages would break translations.
It may be a lot of work, but it can be done with enough dedication. Thousands of strings sounds a lot, but you can start little by little. Also, most probably not every tool needs to be renamed. I mean, many Part, PartDesign, Sketch, Arch commands already conform to the [Workbench]_[Tool] style. There are a few that don't, like I said, TechDraw_NewArch, for example. At least in the wiki, my idea was using redirects (TechDraw_ArchView points to TechDraw_NewArch), but I feel some resistance to this idea from some of you.

About translations. Yes, it does sound like a problem. But, oh well, I think breaking a few things to improve others on the long term isn't such a bad investment. I think FreeCAD is entering a maturation stage, so I believe some hard decisions will have to be made that maybe break some things of the past. For example, what you propose to move to gitbook, would it be seamless, or would it also break translation?
User avatar
NormandC
Posts: 18534
Joined: Sat Feb 06, 2010 9:52 pm
Location: Québec, Canada

Re: Working on the documentation (was: Arch Window - Glass Panel Area etc in Python Script?)

Postby NormandC » Wed Oct 31, 2018 2:29 am

vocx wrote:
Tue Oct 30, 2018 10:29 pm
Don't you think it's a poor decision to use both names interchangeably?
This has been discussed countless times over in the past and I don't want to repeat everything again, I don't have the time. Please search the forum. I know it's not easy (search kind of sucks), sorry but that's what it is.

vocx wrote:
Tue Oct 30, 2018 10:29 pm
It may be a lot of work, but it can be done with enough dedication.
Dedication, sure. Nothing to it, right? :roll: A handful of guys around here do 80% if not 90% of the work. To be blunt, dedication, I've not seen from many people. What I've seen is plenty of people with big plans who don't follow up and disappear in a short time.

vocx wrote:
Tue Oct 30, 2018 10:29 pm
At least in the wiki, my idea was using redirects (TechDraw_ArchView points to TechDraw_NewArch), but I feel some resistance to this idea from some of you.
Because I have 8 years of experience contributing to the Mediawiki documentation, we've tried many things over the years, IMO redirects should be avoided as much as possible.

vocx wrote:
Tue Oct 30, 2018 10:29 pm
About translations. Yes, it does sound like a problem. But, oh well, I think breaking a few things to improve others on the long term isn't such a bad investment.
Again, who will do the work? As usual, the same handful of guys. How much time would things remain broken? Weeks? Months? Years?

vocx wrote:
Tue Oct 30, 2018 10:29 pm
For example, what you propose to move to gitbook, would it be seamless, or would it also break translation?
I gave Gitbook links in another topic. Please read the one about FreeCAD Documentation. And please search for the discussion about it in the forum.