DISCUSSION: Documentation - Nomenclature - Parameters/Arguments & Attributes/Fields/Properties

[wanderslth]

Trying to sort out how to handle what is going to be a very common scenario of letting a user pick the fields they wish to return into their spreadsheet. For example, intercom has like ~40 standard fields that they collect and display in their user profiles. So, a function for this might be:

=FLEX("YOUR_TEAM_NAME/intercom-user-list", days, standard_fields)

sample:

=FLEX("YOUR_TEAM_NAME/intercom-user-list", 5, "firstname, lastname, company, city" )

First, naming conventions for us to consider:

• Parameters/Arguments. Please note that both Excel and Google Sheets documentation use the word 'Arguments' instead of our more dev-centric 'Parameters. We should consider whether breaking spreadsheet convention, as we currently do, is worthwhile. For example: sheets custom function docs and Excel docs - click on 'syntax' dropdown
• Fields/Attributes/Properties. I have yet to find an example of separate splitting out of fields/attributes in Excel/Sheets docs; they seem to just add these items in the field documentation themselves. For instance, see Excel's ACCRINT function, and 'basis' argument here and see Sheets ACCRINT function, and 'day_count_convention' argument here. However, we need to land on a naming convention for this. In an 'enrichment' lookup, it would be pretty easy to land on 'fields' as the convention. However, if we had something like the ACCRINT functions above, then you have numbers 1, 2, 3, 4 meaning different things and are not really 'fields', but more controls. Would 'Attributes' or 'Properties' be more general and encompass both? I'm fine with either -- but will use attributes below for simplicity.

Some research on this:

• Excel Argument usage
• "You define parameters, and you make arguments."
• "an attribute is a variable of any type that is declared directly in a class while a parameter is a variable defined by the function that receives a value when it is called."
• $(".something").attr( { title:"Test", alt:"Test2" } );

---

Second, we need to consider how to add these list of attributes in our syntax. We've kludged this currently -- for instance, see our currency conversion Notes:

The following currency types are allowed: CAD, HKD, ISK, PHP, DKK, HUF, CZK, GBP, RON, SEK, IDR, INR, BRL, RUB, HRK, JPY, THB, CHF, EUR, MYR, BGN, TRY, CNY, NOK, NZD, ZAR, USD, MXN, SGD, AUD, ILS, KRW, PLN

This is fine, since a) we're just talking currency options and b) we can presume the end users could google 'south african rand currency abbreviation' to determine that the correct one to use is ZAR. However, this won't work with profile fields that are more extensive and/or confusing.

As an example, see the last page from Mattermark here, which describes the "supported fields" for their final custom function:

https://static.helpjuice.com/helpjuice_production/uploads/upload/image/2365/104704/Excel_Add_In_Set_Up_Doc.pdf

Long and short, we need to figure out the following:

• Naming convention for fields/attributes
• When we use them (do we go through the trouble of defining all those currencies above or just leave those in the notes?) Do we only do this with confusing fields? What if we have something like =ACCRINT where we are using numbers as controls do we define in the parameter list or in a separate attribute list (ie, explanations of these controls are non-trivial)
• Where do we provide this list of attributes in our current documentation and how to we expose this in front-matter/yaml. For example:

Title
Description
Syntax
Parameters
Sample Usage
Notes

Might become:

Title
Description
Syntax
Parameters
Attributes
Sample Usage
Notes

Main issues I see: A) sample usage may get buried with a long list of attributes and B) where attributes don't apply, you will have a blank spot, like notes. Maybe attributes is optional based on the YAML (and/or turn on/off able in the UI).