Make reference topic titles consistent

[Doug-AWS]

We decided that all module README files should have an "H1" with the short service name only:

e.g.

# Amazon ECS

[Rukenshia]

I'd like to update this, what is the preferred naming @Doug-AWS ?

[Doug-AWS]

Start with the official short name, which you can get from https://docs.aws.amazon.com/index.html#lang/en_us, such as "Amazon API Gateway". Then append "Construct Library". So EC2 should be "Amazon EC2 Construct Library".

[eladb]

Let's also change all READMEs to use H1 ("#") instead of H2 ("##") for the title.

At the moment, the first heading in all our READMEs is H2 ("##"), and this is merged into the Sphinx topic with the reference documentation.

The H1 of the topic is set to the module name by default, but now the result is weird, because we have two consecutive headings at the beginning of each topic (H1 with the module name, i.e. "@aws-cdk/aws-s3" and and H2 with the heading from the README (i.e. "AWS S3 Construct Library").

We have recently changed how jsii-sphinx works. If the first line of the README file is an H1 (starts with "# "), it will use this as the first header of the topic instead of the module name.

This means that if we change all README files to use an H1 instead of H2, those titles will be used as the topic names. And I think that makes more sense then the JavaScript module name (esp. given our cross language nature).

Since these topic names are going to appear in the side-bar of our docs website, they should be concise, so I suggest just use the name of the service ("Amazon EC2") for those.

Thoughts?

[Doug-AWS]

Any progress?

[Rukenshia]

Sorry, I didn't have time to pick this item up again and probably won't anytime soon.

[Doug-AWS]

I don't see this as a P0 or even P1. I'm closing and we can worry about the "nice to have" stuff later.

[eladb]

This is about the README file headings, reopening. We do need to make them consistent.

[Doug-AWS]

I'll try to tackle the headings as I start pulling the info from the readmes as examples. How's that sound? For the existing readmes, that's ECS, CodePipeline, CodeBuild, CodeCommit, so I'll have a PR for those (if they need changing) by EOW.

[ghost]

Can this be closed?