Tracking bug for things related to launching a well-produced website:

• Review this list.
• Review this list
• Automate broken link checking
• Hook up some form of analytics we can query.

• Add back serverless example
• Change current Programming the Cloud tutorial to Programming containers
• Address Luke's high-level feedback below

1. The Programming the Cloud section no longer really feels like programming the cloud - there are no high level managed services being programmed here (like Table or HttpEndpoint or Topic or even Function). I suggest we'll want to have three top level sections: (1) Programming AWS (2) Programming containers (3) Programming the Cloud.
2. The container example is nice and relatable - but perhaps too relatable again in a different direction it's not clear why this is any better than a similar docker-compose example. In fact, as written, I'd say it's tenuous that it actually is better. There's a subtle (but important) point that it is better because of the build support even when targeting a production environment - I think we will need to explain the core to what's different here - and why that difference is central to what makes Pulumi unique (not just another one off thing we did "differently") - which I believe is true - the core model that cloud applications are made up of both application and infrastructure code which can and should in many cases version together - the same thing that motivates lambdas as lambdas and our overall @pulumi/cloud model. There's also the claimed benefit that we allocate the ECS cluster for you - but that's really an antipattern - you shouldn't be deploying a whole cluster just to host a single app! The real "magic" of the container support is that it can be combined with the rest of our offerings, in both direction - fixed AWS infrastructue as well as high level functions, APIs, tables etc.
3. Related to these points - this makes me even more eager to get to the one example which really highlights Pulumi all up at once - something that feels more like what we've used for LM or for our PPC or even in the containers unit test. Something that is really more fundamentally uniquely "Pulumi".

Create a tree of documentation titles and which section they should go into. This will then turn into individual issues that everyone can contribute to.

Example from Joe: how config precedence works.

The space taken by the header makes it so that when you try to go to a section anchor, the section name is cut off. I verified that removing the header makes the anchor behave as expected.

Current:

Expected:

The <hr> defined in footer.html is misbehaving and moves around the page depending on your zoom level. This is only an issue with the new navigation in the master branch (production is fine).

Per @joeduffy's feedback, add previous SDKs and changelog link.

Proposal: keep changelog structure as-is, and add anchor tags to a specific release.

Example:

For pedagogical purposes, it would be useful to render the runtime code differently. There is likely a plugin for this.

I'm having an issue in the quickstart, which could just be operator error.

• Page: quickstart/overview.html
• Section: Packages

I read the instructions below as saying I can use "npm link" or "yarn link" equivalently. Note that I'm using npm.

The following three packages are included in the Pulumi Cloud SDK by default. Before using any of them, please remember to run npm link or yarn link in the consuming Cloud Application’s root directory.

The 3rd step below fails for me:

$ cd myapp
$ yarn link pulumi
$ yarn link @pulumi/pulumi-cloud   <<<<
$ pulumi preview

with this message, indicating the message isn't available in npm. Does this mean I have to use yarn? Will it be published to npm?

Kims-MacBook-Pro:pulumi kim$ npm link @pulumi/pulumi-cloud
npm ERR! Darwin 16.7.0
npm ERR! argv "/Users/kim/.nvm/versions/node/v6.10.2/bin/node" "/Users/kim/.nvm/versions/node/v6.10.2/bin/npm" "link" "@pulumi/pulumi-cloud"
npm ERR! node v6.10.2
npm ERR! npm  v3.10.10
npm ERR! code E404

npm ERR! 404 Not found : @pulumi/pulumi-cloud
npm ERR! 404
npm ERR! 404  '@pulumi/pulumi-cloud' is not in the npm registry.
npm ERR! 404 You should bug the author to publish it (or use the name yourself!)
npm ERR! 404
npm ERR! 404 Note that you can also install from a
npm ERR! 404 tarball, folder, http url, or git url.

Today we check in the results of make generate into the /packages folder. But this generally isn't want we do for generated sources.

Let's back out those files, and then just add the script or two needed to build/sync the various dependent repos so that make generate does all it needs to.

Since there is only one container with one exposed port, we can just use the no-arg version of getEndpoint().

See pulumi/pulumi-cloud#234 (comment)

It pushes the content below to "below the fold" which is not great. Also, update to the latest logo.

Remaining TODO:

• [P1] Initial creation of content
• [P1] Document pulumi.zip installation and setup correctly
• [P2] Colorized syntax highlighting in code blocks
• [P2] Cross-link scrolling offset (not visible after clicking link)

Have the first step not use the userData definition, then have customers add it as a later step. The downside is that you have to re-provision the VM, as the update can't be applied to a running VM.

A bit of feedback from customers on the M8.1 Quickstart docs:

There is a typo on the first page: it says to yarn link @pulumi/pulumi-cloud, but that should be @pulumi/cloud.

It seems like we ought to have a new section: "So you've got a Pulumi program, and want to build/deploy it, how do I do that?" Everything is geared towards starting from scratch, so there are steps missing. For instance, it should tell you to yarn install, how to find out what to yarn link, how to know what configuration variables to set, etc.

There are other missing steps. For example, it never tells you how to compile your TypeScript which, though orthogonal to our tool, we should do if we're going to use it in our samples.

The layout of the Quickstart pages are a little confusing, because clicking on the link to Quickstart then puts you on a page with many links, including Overview. Why not just start there automatically.

Let's do one more pass over the Quickstart "as a customer would", after the above changes, and ideally from a clean machine, just to make sure we've ironed out all the kinks.

@ellismg and @chrsmith: the docs repo still has git LFS in .gitattributes, which causes my Git clients to prompt to install LFS. Can we safely remove this?

Right now we check in our releases to git via Git-LFS.

We should stop doing that as we are running out of space. Long term we should be serving them out of S3 (proxies by the docs website to do an auth check).

If we need to do something sooner we can just download the binaries from S3 into the releases folder on the docs web server.

Sometimes we have important information in a "Note:" paragraph, which is too easy to miss.

I like generally like how Azure does them, though I'm not a fan of the current color scheme:

https://docs.microsoft.com/en-us/azure/azure-functions/functions-proxies

For the AWS example, it's not too bad, but the voting-app one might not be great. I'll be adding back url-shortener which is super inexpensive.

In the quickstart flow, add an example that shows how to use and configure secrets. Related to pulumi/examples#6

In preparation for private beta, ensure basic instrumentation with Google Analytics.

Today we are just checking the results of typedoc into the repo. This provides a pretty disjoint experience with regard to UX, and also prevents cross-module linking. (e.g. pulumi-cloud referencing types in the pulumi package.)

And, to make matters worse, because typedoc emits files prefixed with an "" we need to contort Jekyll to include those files, since the default is to assume files prefixed with "." or "" are not to be included with the website.

Options:

• Create our own plug-in and template and continue to use typedoc. Hopefully find a workaround or fix for their file naming convention.
• Use typedoc's ability to output structured JSON, and build our own template/system that is better integrated with Jekyll. (Using the "collections" or "data" features.)
• Something even better.

I need to check the other platforms, but I saw that our main title font is not rendering correctly on Safari on a Mac. Might have been caused by my recent style changes.

Customer feedback was most backend devs are not familiar with JavaScript. Let's use JavaScript as default, so that TypeScript is not an adoption blocker.

There's a bunch of places in the text where the version is hardcoded. For the text itself, use Front Matter.

(Assuming bugs around naming are fixed)

In docs, suggest that customers prefix their resources with a short name. Then, they can create access keys that are limited to that name prefix.

See pulumi/examples#7

@ericrudder commented on Mon Nov 06 2017

credit to donna:

we should create a known issues page, and make sure it's linked to in our documentation, and every issue has a link to a GitHub issue

@joeduffy commented on Mon Nov 13 2017

I am okay letting this slide to M9. /cc @lindydonna

@lindydonna commented on Mon Nov 13 2017

Sorry to drop this. Do we need more than a GitHub wiki page? Are we assuming that everyone who needs to see it will have access to GitHub?

@lindydonna commented on Mon Nov 27 2017

Ping @joeduffy and @ericrudder. If we're assuming that everyone will have access to GitHub, this is a very easy item. If not, then we'll need to link to issues in some other way.

A simple example that shows deployment time vs. runtime (f.k.a. "inside" vs "outside") show the difference between getting the current date/time inside the body of a Lambda vs. a declaration outside.

Edited: The work for this is tracked in the docs launch spreadsheet

If you are not authorized to access the website (GitHub account authorized, but not on a whitelist) we should provide that information to the user. e.g. "You were not on any whitelisted GitHub organizations or email domains. Please contact [email protected] if you believe this is an error."

We have a Pingdom account, we should use it. Might require some shenanigans to have it send authorized requests as well as confirm unauthorized requests are stuck at the /welcome page.

Once pulumi is no longer on the npm link path, fix up the documentation.

For next version of docs site, would be useful to have a staging version to see changes live. This can just be a VM to host the docs as we do today.

This issue is mainly for me to track product changes that will impact docs.

Names

• Names of products (managed service)
• CLI name (pulumi invocation)
• package names (how you reference them from npm, how you reference in your code)

Terminology

• "Pulumi program" vs something else

CLI functionality

• --local requirement for pulumi stack init
• pulumi init
• Verbs for config

Stack identity

• How is a local stack identified?

Config

• How to use config in your code
• How to define config in config file(s)
• How to create a secret value

There are very long documents that are not well-structured. This issue tracks putting them in the new doc layout and making them more focused.

We might need to add a Jekyll module. Triple-backtick "typescript" seems to still render as JavaScript.

In https://docs.pulumi.com/quickstart/aws.html we yarn link @pulumi/cloud as part of setting up your project, but I do not think this is needed.

Document how to get started using the Pulumi Cloud Management Console.

• Logging in
  • Explaining our use of GitHub for access and auth
• Standing up and attaching PPCs
• Configuring the pulumi CLI (set PULUMI_API env var)
• Navigating a Stack
  • Resource list
  • Accessing logs
  • Accessing update history

/cc @ericrudder Anything look missing to you?

• Document top-level flows like using TypeScript, etc
• Document current config precedence

Joe's feedback in #20:

It seems like we ought to have a new section: "So you've got a Pulumi program, and want to build/deploy it, how do I do that?" Everything is geared towards starting from scratch, so there are steps missing. For instance, it should tell you to yarn install, how to find out what to yarn link, how to know what configuration variables to set, etc.

There are other missing steps. For example, it never tells you how to compile your TypeScript which, though orthogonal to our tool, we should do if we're going to use it in our samples.

The layout of the Quickstart pages are a little confusing, because clicking on the link to Quickstart then puts you on a page with many links, including Overview. Why not just start there automatically.

Let's do one more pass over the Quickstart "as a customer would", after the above changes, and ideally from a clean machine, just to make sure we've ironed out all the kinks.

Customer was not familiar with yarn and why he'd use it. Let's make it clear that you can also use yarn, but default flow should be npm.

screenshot attached

From a private email thread with Joe, he thought it might be interesting to take some existing web applications and show how they’d be done idiomatically with Pulumi.

git clone https://github.com/pulumi/template.git

A recent PR fixed a broken link. It would be cool if we had automatic ways to detect that, e.g. running https://github.com/stevenvachon/broken-link-checker as part of our build/publish process.

It would be useful to have a top-level article that has the content of Pulumi Concepts.

Nice to have: add some diagrams to illustrate the concepts.

To start, just replace the way we're using index.md, so you go right into Overview (or such) and other articles in the section are listed on the left.

For instance, if you're in any article in the Quickstart section, you'd see:

• Concepts
• Overview
• Programming AWS
• Programming the Cloud

ideally, we'd use some JS voodoo on the "huge" gray boxes in the doc, to "improve the flow when reading." ... e.g. for things over 25 lines, we'd preview 10 or something and show an "..." or more or something like that.

not urgent, however, a nice to have if our output is really verbose.

maybe we get for free if we pick up vscode editor and can just apply policy.

Spend 10 minutes and see if this would be useful. (Or other similar documentation apps.)

www.gitbook.com/
readthedocs.io

etc.