Full API description

[Jacksotnik]

Hello. Do we have any full api description? In readme you described some functions like: ".registerHandlers" ".emit" ".dynamoDBTableName"

but where i can see full possibilities list? Not just described in samples

[linslin]

For generating a API Documentation based on JSDoc the SDK developers should start to create some DOCBlocks in the first place. Those are totally missing.

Some pull request try: https://github.com/alexa/alexa-skills-kit-sdk-for-nodejs/pull/92

[EtharAlali]

+1 for me too. Just to be clear, yes we can read the code, but from a point of productivity, it means:

1) Going to find it 2) Checking it's the right code to read 3) Checking it has tests to document the code (note, ASK does not - tests are documentation) 4) Checking it's not abandonware (it is GitHub after all) 5) Making sure we have all the NPM dependencies to then go and trawl if it uses a library we're not familiar with

For people trying to balance writing code with running a business, reading through code isn't always productive and there is way more uncertainty about finding the answer in a reasonable time. If folk are going to give a "read through the code" response, then it conveys that they don't understand the variable demands of running a business or working lean either. So can we not have that response to genuine queries from people seeking help please?

[knowlsie]

+1. I gave this a shot (https://github.com/alexa/alexa-skills-kit-sdk-for-nodejs/pull/96) but they updated before accepting the pull request, and I'm not sure I'm going to keep updating the PR, as I suspect they want to rapidly release features so will keep ignoring it. While this is 'agile' software development - working and fully-featured software over working and fully-featured documentation - it's a little annoying. On the other hand, I made a bunch of other style changes in that pull, and I'm totally happy just to write some DOCBlocks, if that is much more likely to be actually merged.

[EtharAlali]

It's a real shame. Sorry you had that happen. That's a bummer and chances are it'll be obsolete by the time it merges, so I fear you're right. It'll never get merged. After all, working lean should minimise waste and unfortunately, all that developing software in isolation of it's users needs does, is just offset waste from the development process/team into the user team, which hinders adoption and impacts productivity.

The way I have tended to get some of this whilst maintaining development throughput (where appropriate) is literally to publish the UAT screencast vids of the automated UAT process at work. I tie it into the CD pipeline, as it goes through a "stub client" (based on Selenium, CasperJS etc.) anyway, which means if they're testing an API by pasting in code for their Lambda console (as opposed to just hitting endpoints or running mocha and mocking/faking/stubbing the API calls) the result is a video showing an end-to-end process on a success. Put the code usage in the test names and it's done. Auto-publish these vids straight on to the dev docs on a green and voila.

[knowlsie]

Not a big deal at all, I'm used to that sorta thing. Also not sure those DOCBlocks were perfect anyway, maybe I rushed 'em a bit by trying to change everything at once; your doc pipeline does sound pretty neat though, it's certainly not a bad idea to turn UAT into docs as it pretty much guarantees your docs take everything into account. Anyway, I know this SDK reasonably well, I'll write you guys some new DOCBlocks when I have time this week. Hopefully if I only add documentation and change zero code, it will be easier for them to merge it, and easier for me to update it if needs be.

[EtharAlali]

Cool. Thanks man!

[avishaan]

@EtharAlali they had one release since Feb. I don't think that's so "agile" that they can't update their documentation a little bit

This is a real shame, I was debating integrating with Alexa but for something so poorly maintained I'm going to pass and see if Google Home is a viable option instead. Being a part of a poorly maintained ecosystem is a nightmare

[EtharAlali]

mmm... perhaps. I agree with you, so I've just ditched the ASK-SDK completely, it doesn't do the job atm. So I've started refactoring to pull it back out. Not worth the waste of time.

[knowlsie]

So I can tell you how every line of this code works, but hell if I can JSDoc it without burning days of my life. I tried and, I just remembered what an absolute mess of binding this all is, and it's a real stuggle to get any of it expressed in a format that makes a nice 'readthedocs' type thing.

On the one hand, I'm a fan of this SDK, because it's actually a fantastic tool for beginners, it's super easy to learn, and it gives results quickly.

On the other hand, I'm just too busy to document it with its current style. Here's some examples: within your handler properties, this.response, this.handler.response, and this.handler.response.response all refer to different things, and in fact this itself links back to some totally undocumented handlerContext variable which itself is tough to document because it's never returned at any point by anything, but is of course bound to any this-es you include in your handler objects. And though you define these handlers as objects, they aren't really objects at all, but things to be fed into an EventEmitter, with the weird bindings set up as they are... Another of my favourites is that it exports (globally) this variable called StateString which is literally just the string 'STATE'. It's so pointless.

So sorry guys, feel welcome to take a shot at it yourself. I'm going back to F# 👍

[jchiversAMZN]

Hey all, many thanks for the feedback on this. I agree that we've done a poor job wrt documentation of our SDK.

It's a tool we use internally to build skills ourselves, and as our team is (mostly) fixed in terms of engineers, once learnt, there's less motivation by us to then go back and document such; even though it's the right thing to do.

In the coming weeks, we're to launch a new version of the SDK, along with an MVC framework - and it's documented end-to-end as it should be.

[EtharAlali]

OK, cool, thanks for letting us know. I've ditched ASK for now, as it was totally killing my productivity. Went back to thy olde ways. Not to take anything away from anything knowlsie's said. I'm damn sure it works fine, but if we can't have that communicated in a consistent manner, or we haven't invented telepathy by then, then it's as good as useless for the recipient. I'll certainly try again when the new version is out though. Sure as hell not given up for good.

Thanks again!

[rmtuckerphx]

@jchiversAMZN When you say "a new version of the SDK" that will be available "in the coming weeks" do you mean an evolution of the existing SDK or a start-from-scratch replacement?

[jchiversAMZN]

@EtharAlali - understood, and I appreciate your input - it's clear we need to do a better job in this regard.

@rmtuckerphx - we're in the process of finalising the details. We currently have a v2 SDK coupled with an MVC Framework that supports new + upcoming Echo hardware profiles (e.g. devices with screens). We want to provide a single SDK + MVC against which you'll need to write and manage a single skill source base.

[timoa]

+1 for the JSDoc

[btburton42]

@jchiversAMZN what's the status of that newer repo? Do you have a public facing link, or a time that it will be available?

[Cocco17]

+1 for the JSDoc

[tianrenz]

Hi all,

Thanks for your support of the SDK. As of yesterday, the new ASK SDK v2 for Node.js has been released. This newer version offers better support for type definition. You can check out our wiki here. Also, we added a gulp task to generate typescript docs, so you can generate the docs for yourself!

Closing this issue for now. Please feel free to open a new issue using our template if you have any further questions.

[EtharAlali]

Hey. I know it's not the done thing to drop a message here after closing. I just wanted to say the new ASK is superb! So intuitive! Love it!! Great work! Thanks folks.

Anyway, I'll go back to being an a*hle now.