API Help Table of Contents Improvements

[BrianEkins]

Over the years, there has been some discussion about improving the help documentation's usability. One area of possible improvement is the table of contents. It seems everyone has a different opinion about what's best, so I thought it would be good to open up the discussion to get feedback from those of you that use the documentation on a regular basis.

Option 1: Here's the current table of contents. The Reference manual consists of two large lists; one for all the objects and another for the enums. I think this has worked OK in the past, especially since most of the API has been limited to Fusion's design capabilities. One advantage to this big list that I only recently heard about is that when expanded, you can use the browser search function to find topics.

Option 2: With the addition of all of the new CAM functionality in the API, it might be best to break up the different categories, as shown below.

Option 3: Another suggestion is to break it up even more into sections that correspond to the C++ folders where the header files are.

Option 4: This option is something I just recently thought of, and it can be combined with options 2 and 3 above. This removes the "Objects" and "Enums" folders under each category by combining the Enums together and having a single "Enums" folder at the top level. This means there's no need for the "Objects" folder since the objects can now be moved up one level.

What do you think about these, and maybe you have some other ideas? 

[kandennti]

Hi @BrianEkins .

I frequently use the browser search to find objects.
Since I have to open the tree to get a hit, I find it difficult to use if divided into smaller groups and the hierarchy becomes deeper.

I have not seen any duplicate object names or enumeration types, but considering that there will be more of them in the future, it might be better to divide them into smaller groups than they are now.
I support option 2 or 4.

[BrianEkins]

@kandennti, I don't know why, but I have never used the browser search when navigating the API documentation. After someone mentioned the same concern as you about the impact of breaking the tree up into multiple nodes. They also suggested a possible solution, which would be to create a single help topic that contains a list of everything, objects, and functions that would enable a browser to search for everything and be more complete. It would be a huge file and might take a bit to load, but it would solve the search problem.

Technically, there could be duplicate names but I had always discouraged that because the current documentation system doesn't support it, but that's solvable with the current proposal. The other reason, that isn't solvable, is that I think it makes the documentation confusing. When you read an overview topic and they refer to an object name that is the same as a different kind of object, you're going to think twice about which object they're talking about. You can imagine how confusing it would be if the CAMParameter object was just called Parameter.

[NuofanQiu]

I think option2 is better for me now because I only use API for design currently.

But I think no matter which option will be adopted, it is better to provide a more convenient overview about the total APIs. I think the pdf of the Fusion360 object model is not very convenient and easy to understand by now.

Thank you for your work~

[nnikbin]

In general, I prefer a flatter structure like the current documentation (option 1).

How about having 3 sections named Namespaces, Objects, and Enums under the Fusion 360 API Reference Manual and adding a link to the "Defined in namespace" part of each page that refers to a dedicated page for that namespace containing two lists for its Objects and Enums?

[nnikbin]

Option 4 is somehow similar to AutoCAD ObjectARX and Managed .NET reference guide. Perhaps using AutoCAD Team experience can also be beneficial.

[Jorge_Jaramillo]

Hi Mr @BrianEkins ,

My first source for documentation is CHM API help file which I download with every time there is an upgrade.

I barely use the online documentation, but I'd go with option 2.

Too much sections is not good as in option 3, as not anyone who use it could know exactly the difference between those sections.

Will this update cover the CHM file as well?

In term of improvements, I'd suggest it's more important to have better error messages from functions calls, like in the following example:

if you supply an non planar face to

sketches.add(face)

it will return with error:

return _fusion.Sketches_add(self, *args)

RuntimeError: 5 : Some input argument is invalid.

Why if internally it was checked that 'face' was non planar, it's not being returned in the error message?

Giving better error messages will increase the chances more people get better understanding of the API.

Regards,

Jorge Jaramillo

[NuofanQiu]

I agree with you. Using CHM file is more convenient than using website API doc.

[nnikbin]

Exactly. chm help files are very convenient for me, too. The main reason I prefer them is their separation from non-API documentation. Additionally, the index and search tabs, as well as their independence from an internet connection, are some of their advantages. However, as you implicitly pointed out, a drawback is that they may not always be available for the latest version of the product.

[BrianEkins]

I would expect any changes to be both for the CHM and web versions of the help. As of a couple of years ago, the CHM is updated with every release of Fusion, so you're guaranteed to have access to the same content that is online.

I heard directly from someone with the question about why are there "Object" and "Enum" folders and why not combine them. I think that's a good idea and would get rid of one level no matter which solution is chosen.

[nnikbin]

Except in option 4 which separating Enums does not add one level. Personally I like them to be separated. Maybe because I'm used to it for both Inventor and Fusion 360.