docs icon indicating copy to clipboard operation
docs copied to clipboard

Pulumi Node SDK docs usability

Open jkodroff opened this issue 2 years ago • 0 comments

Problem description

The Pulumi node SDK docs (https://www.pulumi.com/docs/reference/pkg/nodejs/pulumi/pulumi/) have some serious usability problems:

  1. They're reference docs (like stuff in the registry), but they lack the useful left-hand nav that the registry has.
  2. The entire SDK is presented as a single page, which makes navigation very difficult.
  3. Many methods lack examples, so it's very difficult to know how to use them in context. For example, pulumi.jsonStringify.

Suggestions for a fix

  1. The Pulumi SDKs should have docs pages that are in the idiomatic format for the language in question. (The Go SDK does have this quality, for example.) AFAIK, there is no canonical Node API docs format, so the format we use in the Registry is the next best thing.
  2. The node SDK should be broken down into 1 page per module.
  3. We need to ensure that our descriptions for our SDK methods are understandable to a wide audience. "Uses JSON.stringify to serialize the given Input value into a JSON string." doesn't really help me. OTOH, explaining that it's a useful helper function that removes the need for an Apply when writing IAM policies and showing before and after, now I know why I should care and when I should use it.

jkodroff avatar Apr 04 '23 01:04 jkodroff