Target Audience for Help files.

owen_sparks

Hi folks.

Firstly this is not meant to be a winge although it may come across as such.  Sorry for that

I think you're doing an excellent job with regards to tool tips in the regular interface.  (Hover over a button an explanation comes up, hover for longer a deeper explanation is given.)

I wonder if there is a way to tailor the help offered to the user when with regards to featurescript documentation?  I appreciate it's all really new and being built upon every day and am grateful to you guys for putting such good info in already.

However the target audience will have a wide range of experience from user A - who is a professional coder who can easily digest the structure of the code and just want's to look up the input/output of a function they've not used before, to user B - who will need a hand to understand what an Enum is or how to pass a parameter to a function.

The pro doesn't want the information diluted with waffle, but the new user may need a bit more background / hand-holding.

I recall trying to read MS help files when starting to code and practically pulling my hair out at the indecipherable language and thinking to myself that you needed to understand how everything worked to be able to understand the help files, but if you understood how it all worked then you wouldn't need to read the help files...  I ended up abandoning the "dry" help files and used google instead!

One option may be to pepper keywords with links to explanations. Another may be to think of needing 3 key skills, (a) General CAD / Geometry familiarity, (b) Familiarity with any programming language, (c) Familiarity with FS itself.   If a user were able to set an experience level slider, or even set something in their profile then perhaps the help could automatically rebuild to be tailored to suit their needs?

Crap, I'm waffling again, but hopefully you get my drift.

Cheers, Owen S.



 

Dylan_Stewart

The library and webinars/tutorials are a great help, but they still lack in the "next level" area.

There are some brilliant people here who are more than willing to help out (and I think that's just dandy). To be able to cater to everyone in every aspect would be a difficult task to accomplish. 

I would definitely consider myself a novice when it comes to modifying the machine but I am super excited about it. 
I've taken a few programming classes and watched about 1000 hours of 'How To's' on YouTube and still some of these guys are light years ahead.

They say some people "just get it" while others "aren't cut out for it".... I refuse to believe that. Everyone has their own way of learning. 

kevin_o_toole_1

This is an interesting and fruitful area of discussion. Thanks for bringing it up, Owen.

You're absolutely right that the documentation is just a start of what could be offered, and you're right that our current docs are not kind to those lacking experience. But even more than experience, I think right now (two months and three releases in) the people who are thriving in FS are just remarkably persistent: seeking out solutions, and experimenting with possibilities where the documentation doesn't provide answers (or at least, doesn't give answers without a lot of diligent searching).

It's easy to let this conversation get abstract, so let's be concrete. There's several dimensions in which our documentation ecosystem can grow:

• Long-form tutorials (like the Slot tutorial)
• Short-form guides (on the modelling level e.g. how to refactor reusable code, best practices with FS ids)
• "FeatureScript guide" sections (At the language level e.g. more on creating and overloading functions)
• High-level articles (What needs FS can fill, how to make your feature tree robust and maintainable in general)
• Video tutorials and webinars
• Practical examples for common tasks (imagine public documents with features that show and explain, e.g. how to evaluate anything about an edge, or a feature that interactively shows the results of various query filters, or a feature that robustly creates coordinate systems in n different ways, etc... A cookbook of useful FS recipes)
• IDE improvements (e.g. Making some of this documentation more present while coding)
• FS doc page improvements (e.g. search!)
• Error reporting improvements (In my mind, errors thrown by FeatureScript are definitely documentation. Getting the right info in the right place here is usually an exercise like trying to squeeze tightly on a handful of sand, but there is absolutely room to improve)
• Others?

Naturally, we can't do everything all at once (and even if we could, we'd rather have a few, good, consolidated resources than a myriad of distributed, redundant resources with no clear learning path). But everything above is a possible focus.

So I ask you all: What flavors of documentation would be most useful?

Dylan_Stewart

@kevin_o_toole_1 I would vote for webinars/video tutorials as well as your cookbook idea. 

Maybe the very basics all the way to import/exporting, get/set and other advanced methods. 

lemon1324

kevin_o_toole_1 said:

• IDE improvements (e.g. Making some of this documentation more present while coding)
• FS doc page improvements (e.g. search!)
  

As one of the FS users who's already comfortable with scripting/reading documentation, this is the most frustrating part of writing FS.  In particular, the documentation isn't currently cross-linked (e.g. if a function has parameters of Vector and Plane, the documentation for Vector and Plane types should be linked), and is also not on a single page for Ctrl-F searches.  There's a couple things where it's not obvious to look in the FS Library documentation, which is all one page and searchable, or in one of the many different language reference pages (which usually results in at least three searches before I find what I was looking for).

For a few functions, I've actually had to read the source code itself and not the documentation to figure out what all the options are and what they mean.

My 2 cents here: Improve the documentation first, because this will help everybody, and also act as a foundation for tutorial/cookbooks; as soon as a user gets to the point where the tutorials are less useful, they'll need the actual documentation too.