Documentation updates?

  • 1
  • Idea
  • Updated 2 years ago
  • Planned
I've been using Skuid on and off over the last few weeks. I've not delved too much into the Javascript side of things, as I've been trying to explore how far the declarative features can go.

Whilst I like the tutorial, use case focus of the current documentation, I'd really like to see some more material around what Skuid is really doing under the covers. Sometimes Skuid can feel a bit of a black box and figuring out why things aren't working as expected isn't easy, and I find myself having to imagine what Skuid is doing, and then testing those ideas to see if I can confirm them one way or the other. There's also the added element of 'Is this a bug?' (I guess the corollary to this is perhaps documentation of best approaches to debugging, or even new debugging tools?)

Irritatingly, I don't really have any examples to hand as I think of this - the only thing I can grasp towards is something like 'order of execution' - for example, I've been caught out by the order in which models are listed having an impact on linking model records to one another. A specific example I encountered is 'Context' - I'd like to see more on how that works.

Maybe I just encountered some gotchas along the way and should have catalogued them and posted them as a list. But I'm posting this in the hope that 1. Skuid say "We're already working on this" 2. Other people are able to say "Yes, I'd like to see x, y and z" or even 3. People say "What are you talking about? I don't agree at all!"

I don't know if the Skuid team see people being tripped up by the same gotchas, but that may be somewhere to start.

Sorry if that sounds a bit on the negative side, I love the tool, but it feels like I've really had to fight to get into it!
Photo of Gary

Gary

  • 1,518 Points 1k badge 2x thumb

Posted 4 years ago

  • 1
Photo of Ken McElrath

Ken McElrath, Official Rep

  • 1,214 Points 1k badge 2x thumb
Thanks for your honest feedback Gary. I'll let others reply to specifics, but I want to encourage you by saying yes, we are working on this. In fact, we are in the process of creating an entire online Skuid curriculum. Many of our help files and documentation found at help.skuidify.com are direct responses to specific questions and use cases, pulled from a rich knowledge base being developed in this community. But we always need more. And more structure. We've hired a full-time documentation specialist to tackle the very issues you mention, and much more. In the meantime, please feel free to post any "gotchas" as you encounter them here in the community. Our users, champions and Skuid staff will respond as quickly as possible to remove any roadblocks. 
Photo of Gary

Gary

  • 1,518 Points 1k badge 2x thumb
Ken, appreciate the quick reply, especially as you must be extremely busy preparing for Dreamforce :) I look forward to learning more about the curriculum.

I've added a few other posts with things that came to mind as I was typing, and I'll make more of an effort to post things as I come across them.

Thanks again!
Photo of Josh Cutler

Josh Cutler, Official Rep

  • 864 Points 500 badge 2x thumb
Gary, I appreciate your feedback. Ken's response perfectly encapsulates my thoughts on your comments, so I'll address some of the details.

I think some of the "black box" feel is a consequence of our current state of documentation. As you noted, our tutorials primarily focus on how-tos and use cases. Which is a valuable resource to our users... but not particularly helpful when you really want to take a look behind the scenes at what Skuid does and how Skuid does it. That "deeper magic" material, more often than not, exists in the community forum, which means the data is in an unstructured format and can be easily missed if you don't type in the right search terms. We are in the process of structuring the meaty content of the community and incorporating it into the tutorials, but the work is far from over. The online curriculum we are developing should be in alignment with your needs and I look forward to your response to that material!

Your input is welcome and helps us focus our resources on practical and useful features. For example, you are right that Context conditions are sparsely represented in the tutorials currently. I will fix that. Also, I think a "best practices" for debugging guide would be a handy addition to our knowledge base. Thanks for the suggestion!

Thanks again for your feedback! When you said you were sorry if your feedback sounded a bit negative, I couldn't help but shrug and say, "you're right. I've got work to do".

Sincerely,
the full-time documentation specialist.
Photo of Gary

Gary

  • 1,518 Points 1k badge 2x thumb
Hi Josh,

Thanks for the reply. Indeed, the current tutorials are valuable, and I certainly managed to learn the ropes with them pretty quickly, and you're spot on on the community point - I'm sure it'll help you discover some initial areas to target.

It sounds like you've got a lot planned, and I look forward to seeing your work in the future :)
Photo of Shannon Hale

Shannon Hale

  • 312 Points 250 badge 2x thumb
It's been a while since we've responded to this, but I wanted to flip the switch to Planned, and provide an update.

In the last 12 months we've been updating some of the documentation (the developer documentation in particular), and we're currently in the process of moving our documentation off of ScreenSteps and onto docs.skuid.com. We have a number of additional enhancements planned, including more sample code, more robust API documentation, and a code repository. We'll be rolling this out over the coming year.

If you have concerns with a specific piece of the documentation, please do submit an idea and let us know the page and what's missing. We want to improve everything but it takes a while to review everything, so giving us a place to start will never be seen as negativity - we know we have work to do here!
Photo of Gary

Gary

  • 1,518 Points 1k badge 2x thumb
Thanks Shannon, good to hear, and thanks for the blast from the past - can't believe I started with Skuid 3 years ago! :D