DISCUSSION: Documentation - Return 'Properties'

[wanderslth]

This issue will soley focus on 'return' values; to keep things focused, we can deal with other patterns (naming conventions, etc) in a different issue.

Per discussion this afternoon, need to determine how to be clear to end user what return values they're getting from the function.

Excel/Sheets Docs

For reference:

• Excel function list descriptions
• Sheets function list descriptions
• Mattermark function properties

A common pattern is that for most functions, the description begins with "Returns...." Or, you'll see something like 'Coverts..." Regardless, 'Returns...' probably would be a good pattern for us to use across the board, when relevant.

Examples

Below are the three current Intercom descriptions converted to a more formal 'returns' pattern that provides details on what the function does. Drafty, but here for discussion/thoughts. Items you'd want to hit on early are:

1. Type of function (e.g. currency conversion would say 'Converts'; while currency list would say "Returns a list...")
2. Is it returning a cell, a row or a list
3. What properties is it returning.
4. Are those properties arbitrary (user decision) or does it just dump all of them out (function creator decision)

Intercom User Lookup
Looks up information about a user from Intercom

to

Intercom User Lookup
Returns a a row of user properties, including foo, bar and foobar. See below for a list of all return properties.

---

Intercom User List
Lists all users created since a specified number of days ago

to

Intercom User List
Returns a list of users and their properties based on creation date, including foo, bar and foobar. See below for a list of all return properties.

---

Intercom Event List
Lists all the events for a given user

to

Intercom Event List
Returns a list of events for a user, including foo,bar and foobar.  See below for a list of all return properties.

---

Properties syntax

For something like Crunchbase, there are literally 15+return possibilities, of which we can allow users to mix and match. When we created the YAML for the documentation, I believe Aaron created a bookmark for properties, since we knew we'd have to deal with them. Might be the time to investigate these further, particularly since any CRM-type lookup (hubspot, intercom, crunchbase, etc) will have a potential to return a ton of values.

Below is the stub I created back in the day for the Crunchbase function Aaron crated for jason based on the DB. This type of 'properties' methodology would also provide for typing as Aaron voiced this afternoon...

---

Organization-lookup

Returns information about organizations, where names are a list of permalinks or domains and properties are a list of properties to return.

Sample Usage

• =FLEX("jrowley/organization-lookup", "apple.com", "total_funding_usd")
• =FLEX("jrowley/organization-lookup", "apple.com", ["total_funding_usd","last_funding_on"])
• =FLEX("jrowley/organization-lookup", A1, B1:F1)
• =FLEX("jrowley/organization-lookup", A2:A4, B1:F1)

Syntax

FLEX("jrowley/organization-lookup", names, properties)

• names - The domain name(s) of the organization (e.g., apple.com) or related Crunchbase permalink (e.g., https://www.crunchbase.com/organization/apple)
• properties - the values to return for the organization name (see property choices below).

Properties

• name - This is a desscription.
• permalink - This is a desscription.
• rank - This is a desscription.
• domain - This is a desscription.
• homepage_url - This is a desscription.
• facebook_url - This is a desscription.
• linkedin_url - This is a desscription.
• twitter_url - This is a desscription.
• logo_url - This is a desscription.
• address - This is a desscription.
• city - This is a desscription.
• state_code - This is a desscription.
• region - This is a desscription.
• postal_code - This is a desscription.
• country_code - This is a desscription.
• email - This is a desscription.
• phone - This is a desscription.
• status - This is a desscription.
• short_description - This is a desscription.
• category_list - This is a desscription.
• category_groups_list - This is a desscription.
• num_funding_rounds - This is a desscription.
• total_funding_usd - This is a desscription.
• total_funding - This is a desscription.
• founded_on - This is a desscription.
• last_funding_on - This is a desscription.
• closed_on - This is a desscription.
• employee_count - This is a desscription.

Notes