AppSheet Help Pages needs re-indexing & re-structuring

LeventK
Participant V

@praveen
@tony
@Peter

I believe the help.appsheet.com pages content order is not in good order/shape which causes a lot of conflicts and mis-understanding between users. Humbly, I think that the correct order of a help page should be like this in terms of readability, accessability, indexability, searchability and headers:

1. Syntax
2. Arguments/Parameters
3. Return Value
4. Examples
5. Problems/Issues & How-To Resolve
6. Refs/See Also

Status Open
0 22 1,537
22 Comments
pravse
Staff

Hi Levent, yes, that would be the way a developer would expect it in reference docs.

I think though that the current approach is also reasonable and might be better for a different kind of user, one who learns best by example. By leading with the examples, they can easily intuit the behavior of the function.

We haven’t had much feedback on this, I believe.

LeventK
Participant V

Hi Praveen,
Yes, you may have a right but I humbly think without knowing the syntax, parameters and parameter types that expression takes than the example might not mean anything to the user even-if he/she is an example-learner. Because if we look from this perspective, the examples can be a lot and there’s no way to exemplify them all. And therefore the user cannot distinguish the usage and difference of the ways of usage for his/her own needs for a particular (or in general) issue(s).

And - though it’s a no-code platform - don’t you think that every single member of this community is a “developer” also? I’m sure you will also admit that there is no way to provide/exemplify every single approach or usage out of thousands of possibilities. So if the syntax, parameters and usage is well-descripted beforehand, than everyone could be able to (or at least try to) construct the expression as per his/her own needs.

Just speaking out loud…

Mike_A
Participant V

To add to the conversation, you both have points. But, as a newer user I find I am often very confused how to accomplish some tasks, and I find my mistakes often come down to a misunderstanding of syntax. Might just be me, but I when to use [ col name ], quotes, periods, etc just seems inconsistent and much of the help text uses generic terms which don’t seem to explain when to use a table name, column name, etc. I am not sure the order of help topics is the core issue, but I do think being more clear on syntax of formulas, REF structures, etc, may help users avoid blindly trying to fix multiple errors. These mistakes increase frustration, makes me feel like I lack an understanding of proper syntax, and make me wonder if this no-code environment requires a lot more database and command structure than I thought would be needed. I regularly use google and excel formulas, including heavy use of things like google query statements and google apps script, but still feel very uncomfortable with Appsheet syntax - and wondering why.

Sorry for rambling, but I do think there is a gap here, and clear and consistent syntax might reduce a lot of user confusion (at least mine :-).

Elijah_Magrane
Participant V

I think this is a very important conversation and I would like to add to it.

In my opinion, appsheet has low barrier to entry but a high skill ceiling. Like many users here (@Mike) I have some technical expertise in other platforms. That being said, I find it hard to transition from an intermediate user to an advance user on the appsheet platform.

For context I have been using Appsheet for a little over a year. I have many other hats at my job but making, deploying, and maintaining apps comprises about 30% of my time. The more I use the platform the more potential I see in it. However, in order to progress as a Appsheet developer I personally need to understand the fundamentals rather than the examples.

Sometimes I wonder how much of becoming an advanced Appsheet developer is having previous technical experience with other platforms or just knowing Appsheet really really well. If it’s the latter, the tools just can’t be all examples, we need an explicit guide. If it is the former, then that needs to be addressed as well (Maybe point us to other 3rd party resources that would help someone gain a better understanding, databases queries, VBA, scripting, etc.).

I think it would be a good ideas take a poll of the user base to determine what their background is, challenges they face when developing apps, and what tools would be helpful to them. In closing I just wanted to say I appreciate both Appsheet as a platform and the community emensly. Thanks to everyone!

Mike_A
Participant V

@praveen - I just thought I should share my “day in the life” learning Appsheet

Apr20, 2019:
Cool. I see more posts on the community. Some wise people are sharing their knowledge to help real users like me! @LeventK just responded to a user yesterday with advice how to handle “cascading” input forms, were one form leads directly to another! Never thought about more than one “hop”, so I start reading…

@LeventK posted a LINKTOFORM formula to use in each form that looked like this:

LINKTOFORM(“Chainsaw002_Form”, “ID”, UNIQUEID(), “Hardware”, [MaxRowColumnName].[Hardware])

I take a look and start wondering… what is the “.” for in the [MaxRowColumnName].[Hardware] section?

So I go to the support pages and check LINKTOVIEW and see the following syntax:

LINKTOFORM(view-name[, column-name, column-value]…[, app-id])

Hmmm… no “.” to be found. Once again I wonder, why did he use “.”? I am somewhat familiar with other environments (like javascript) and start thinking – is this an object? Or is it SQL syntax? The help seems to suggest you just use a view-name, column names in brackets?.. and a column-value … whats that for? And then end with an app-id in brackets? I thought brackets were for columns? Now I am confused…

So I decide to check in an appsheet editor field and see if the examples help. In the equation editor I get:

LINKTOFORM(form-view-name, [column-name1, column-value1, column-name2, column-value2, …], [app-id: TEXT])
with an example of:
LINKTOFORM(“Some Form View”, “Date”, TODAY(), “Color”, [_THISROW].[Color])

This seems a bit more clear. The editor is suggesting column name / value pairs in brackets. Ok. And LOOK! There is the “.” showing up in the example [_THISROW].[Color]. But… I am still not sure what it is for.

I assume [Color] is a column in the _THISROW row, but THISROW is not a column and its surrounded by braces too. So… is [Color] a column in THISROW which is not a column?
I also see a formula TODAY() in this example and the syntax suggests that’s not a column value as its not surrounded by braces, but there is also “Date” in quotes and no brackets. What the heck is all of that? When do I use braces and when do I use quotes?

So now I am even more confused and frustrated. Sometimes we use brackets for columns, but maybe values too? And when is "Color" not a [Color]? And finally, I still have no idea what the "." is for! The only thing I think that is clear is, the guy asking the question wants to track chainsaws!

(thought to self - this platform is much harder to learn than I realized. I just can’t seem to get a handle on the “language” they are using, and looking at examples to figure out how “.” is used takes way too much time. In fact, the examples are great, but to figure out my specific use case I need to first understand someone else’s table/view/column/formula setup, just so I can figure out how to use “.” properly. maybe I should find a programmer after all…).

Ok… maybe I embellished this a bit, but after a year using appsheet, I am not yet fluent enough to write a LINKTOFORM formula without cut-and-paste from the help documents and examples. In other environments (eg: javascript or google sheets), the order of objects and references seems more clear to me, and over time, I am able to work a majority of time without referring to the help documents. Maybe that’s why they call the docs “reference documents”?

This might just be my brain not working that well (and you could argue my IQ is too low as well), but this if my real-life experience with learning appsheet. To be clear - I really love this platform, and the team behind it is off-the-charts awesome!!! @LeventK just triggered some feedback I thought I should share, hoping it helps make this platform the best no-code solution - period.

Aleksi
Staff

Excellent post @Mike

And the reason for this “dot”, is the Deref. When you add a virtual column with the MAXROW expression, it will create it as a Ref column. And because it’s a Ref, you can use it with the Deref expression like… [RefColumn].[AnotherColumn].

Elijah_Magrane
Participant V

Pretty much sums up my experience as well. Great post.

Mike_A
Participant V

@Aleksi - lol. Yes… over time I figured out this was a DeRef. But the confusing thing is, mixing a deref syntax in the LINKTOFORM syntax assumes you know the DeRef syntax already. I think that can actually cause some confusion rather than clarify things. And ps: thanks for all your efforts to help users. Sharing your knowledge is hugely appreciated!

pravse
Staff

This is a very important thread. I am following and sharing with everyone on our team. It is difficult for us to see our own platform through “fresh” eyes. The expression syntax, especially advanced stuff, is definitely where the no-code promise becomes questionable.

LeventK
Participant V

@praveen
As always, we are ready to give a hand whenever you or the team need.

Kirk_Masden
Participant V

I agree with everyone here that this is an important thread. I think I’m less computer literate than @Mike. Decades ago I learned to do some programming in BASIC but that’s all the programming experience I have. Since then, I’m pretty much limited to spreadsheet formulas. As such, I hope I can add the kind of “fresh eyes” perspective that @praveen referred to.

AppSheet is quite accessible to non-programmers like me – until the need to use expressions in virtual columns arises. Then, the learning curve gets rather steep. The need to use expressions in various situations makes “no code,” a term which features prominently in AppSheet’s promotional materials, feel like a misnomer.

Now, to be clear, even if people like me “feel” that AppSheet is a good deal harder than the impression given by “no code,” I’m not saying that AppSheet is actually misusing the label. I’ve looked at the following blog post on no code and that more-or-less convinced me that AppSheet’s use of the “no code” label is probably technically correct:

I think that for true coders – people who know what it’s like to build an app from scratch in Python or some other language – AppSheet is, indeed, “no code.” The problem is that non-coders like me look at complex expressions and think “How can they say that this isn’t code?”

I think that it’s probably OK for AppSheet to continue to advertise itself as “no code” but that it would be a good idea to prepare new users for the shock and dismay they may experience when they are confronted with the need to write complicated expressions that can even trip up experienced coders. Conversely, if AppSheet only says stuff like

In either case, the main advantage is that employees don’t have to know anything about coding to be able to build transformative applications. (That’s why it’s called no-code development, after all.)

I think some people may feel that they haven’t been leveled with.

It’s a bit of a dilemma but, as I wrote above, I think there may be some value in considering how new users can be eased into to the world of expressions without feeling that this is all a bit more than they had bargain for.

What I have written here is a bit different from the more practical issue presented by @LeventK. I’ve focused more on the gap customers may feel between the “no code” sign on the store window and some of the actual merchandise in the shop. I’d also like to write about issues related to other aspects of this discussion but I’ll do that in a different post.

Aleksi
Staff

@Kirk_Masden Good post! Maybe we should have a separate post for this one but I’m thinking this way… Appsheet is “using” expressions from Excel and gSheet. People are familiar like worldwide with these two programs. I think they don’t need developer skills for using them. Wouldn’t it be the same with Appsheet… “No coding is needed”. Just thinking loudly.

LeventK
Participant V

@Aleksi there are parts that I could agree and I cannot agree with your statement actually. The use of expressions could be alike with the Excel and/or Google Sheet formulas but they are not identical in terms of usage, syntax, parameters, and their usage. AppSheet is not a tableing software or platform at all.

Aleksi
Staff

@LeventK I was not thinking are they same or not. Excel and gSheet formulas are not the same either. But the idea and level is the same.

LeventK
Participant V

I disagree with that too @Aleksi