Roy_043 wrote: ↑
Wed Jan 29, 2020 10:18 am
How can you find out where documentation is lacking?
How do you know if some other user is already working on pages you have set your sights on?...
The only way to really know what needs to be documented better is to go through each page manually.
When I started using FreeCAD, I wanted to build a house, so I looked up the Draft and Arch documentation, and worked through some examples, and learned to use the software that way. Then I decided that the documentation was just not good enough. So I committed myself to improve things.
I started with Draft, and basically tested each command in the Draft Workbench
page, making sure that each worked as described, and if not, I would improve the text, images, examples, and code. Not only did I test the graphical tool, I also went into the source code, and little by little started understanding it. This is helpful in order to write better documentation, as you can explain why things work the way they do, and the limitations.
Essentially, one thing leads to another, and to another, and to another. That's how a wiki works. It's a collection of interconnected pages. So, when you start reviewing one page, it leads you to another page, and perhaps this could be written better, so you improve it, and then you go back to your original page, and then a second link leads to another page that you could also improve, so you do it, and this has more links, so you continue, etc. You can get lost in a rabbit hole pretty quickly, but that's how it has to be done.
My original intention was to improve the Draft and Arch documentation. But I noticed a lot of issues that could be tackled at the same time, tutorials on using tools, so I wrote them, organization of the tutorials
and video tutorials
, how to use the GuiCommand template
more effectively, how to organize the pages more effectively using Categories
, the obsolete nature of the API, etc.
I finished going through the Draft tools, but I actually never started reviewing the Arch tools in a similar way. There is just so much to do.
So, my advice is to just pick something that interests you, but be very committed to it. I would go through each and every command of each workbench, making sure the documentation is up to date with the current behavior. Along the way I would fix many small things, like using example images to show the behavior, using better templates to fill the information of the properties, providing code examples, etc.
Kunda's lists are just to show all pages in a workbench, in order to incentivize people to look at them, and maybe improve them. But we need committed users that are tenacious and willing to work on them for months.
You can't really know if somebody else is working on a page. You just have to monitor the history of the pages to see what has changed recently. In the upper right, there is a Watchlist link which shows you all pages to which you have contributed that have received changes. This allows you to check periodically the information on pages which you have modified in the past.
All of this is done without clear organization at the moment. As I said many times, we just need more users. Once we have enough users, then small teams will form organically to coordinate tasks better, in the case of the wiki, to do better edits and maintain a certain style. Right now, we just need to add more information to the wiki, in order to attract more users to the software, who eventually will become power users and developers.
I think two priorities exist, and that is (1) to update the old documentation (a lot of pages exist but haven't been updated significantly in years), (2) improve the status of the power user and developer documentation. Unfortunately, for the second point, this has to be done by users with enough experience with FreeCAD, particularly with scripting and workbench writing. That is, this has to be done by developers. Unfortunately, developers like to develop new code and not write documentation. Somebody needs to bridge those two tasks.