Docs page not easy to use

[ened]

trafficstars

TLDR: The documentation reference is not as cross-linked within itself as it can be. Features like Globals and Search do not work. Key information is missing in the Media constructor documentation. The latest package version has no public docs (3.5.0)?

Through some googling I ended up here: https://actions-on-google.github.io/assistant-conversation-nodejs/3.3.0/index.html

And wanted to learn about different media types a node-js client could push into a conversation. There is this example:

  conv.add('Hi, how is it going?')
  conv.add(new Image({
    url: 'https://developers.google.com/web/fundamentals/accessibility/semantics-builtin/imgs/160204193356-01-cat-500.jpg',
    alt: 'A cat',
  }))

I clicked on the Conversation class in the left menu, then ended up here https://actions-on-google.github.io/assistant-conversation-nodejs/3.3.0/classes/conversation_conv.conversationv3.html. Image is mentioned in the types and once clicking on it, I end up here: https://actions-on-google.github.io/assistant-conversation-nodejs/3.3.0/classes/conversation_prompt_content_image.image.html.

This is the only way to reach this. Also note that any of the second pages will not reflect in the left side menu. One must click through the page directly and can not browse like other doc tools (javadoc etc).

Clicking on Globals ends up with 404.

Click on Search opens a input field with "Search Index not available". Entering anything & pressing enter leads to 404: https://actions-on-google.github.io/assistant-conversation-nodejs/3.3.0/classes/undefined

I'm looking for other types to push through Google Actions, for example a YouTube link or a HLS video stream. So there should be the Media class: https://actions-on-google.github.io/assistant-conversation-nodejs/3.3.0/classes/conversation_prompt_content_media.media.html. The documentation lacks any information or points on the supported formats.

The MediaObject class contains 4 optional parameters and no description how to use the class: https://actions-on-google.github.io/assistant-conversation-nodejs/3.3.0/interfaces/api_schema.mediaobject.html.

Also note the version (3.3.0) in the URLs, which does not match the current version of 3.5.0. No link to the docs is provided in the Github releases tab, which could be helpful. Old docs version may want to redirect to newer versions.

[Fleker]

Thanks for your feedback. We've updated our reference docs to the latest version, v3.6.0, and will ensure that we always synchronize the reference docs with releases.

Search support seems to be broken in the theme itself, perhaps a result of changes in the Typedoc stack. I will ensure that's fixed (https://github.com/google/typedoc-neo-theme/issues/69).

The broken Globals link is also a known bug in the theme (https://github.com/google/typedoc-neo-theme/issues/67).

The project has a custom left-hand table of contents, defined here to point people to the most important sections. We can add additional shortcuts if there any suggestions (including PromptItem).

I do see that some classes like Media and MediaObject are lacking a bit in documentation, which should be improved. We do have formal documentation on Media Responses which we should definitely link to in our API reference.

With regards to a redirect, we do ensure that visiting the simpler link https://actions-on-google.github.io/assistant-conversation-nodejs/ does redirect to the latest version.

Here are the action items as I see it:

Typedoc Theme

• [ ] Fix bad Globals link in outline
• [ ] Fix search

This library

• [ ] Cross-link to developers.google.com in opportune places like (PromptItem)
• [ ] Add more overviews for classes
• [ ] Add code examples for classes
• [ ] Explore opportunities to provide more info for various fields (eg. the relatively bare ConversationV3 class)
• [ ] Promote more shortcuts to useful areas in the left-hand outline.

Do you have any other feedback?

[ened]

Thank you for your reply @Fleker, really appreciate you have taken so many actions already.

I think adding more technical detail (formats, validations etc) and cross-links to developers.google.com is really useful for new library-users.

[Fleker]

In the v3.7 docs there is fixed search and a number of additional information and examples for core fields.

[ened]

@Fleker So much better! Thank you.

[ened]

@Fleker just small thing - please ensure the link on homepage README points to the new docs eventually:

The 2nd link (reference docs) ends up w/ 3.6.0 still.

[Fleker]

The link points to the generic https://actions-on-google.github.io/assistant-conversation-nodejs/ but it looks like the index.html redirect did not happen.

I've fixed it manually for now.