aws / aws/aws-cdk

sns: Add details to `aws_cdk.aws_sns/Topic.html` documentation

Open
#35,736 2 comments 0 reactions 0 assignees View on GitHub
@aws-cdk/aws-sns documentation effort/small good first issue p2
Dominant language
TypeScript
Stars
12.9k
Forks
4.6k
Avg merge
2d 3h
Merged PRs (30d)
83

Description

### Describe the issue

In comparison to the SQS queue documentation, the SNS topic documentation is lacking depth.

Particular examples:
- https://docs.aws.amazon.com/cdk/api/v2/python/aws_cdk.aws_sns/Topic.html#aws_cdk.aws_sns.Topic.grant_publish -- bad documentation (no explanations of what permissions exactly are granted)
- https://docs.aws.amazon.com/cdk/api/v2/python/aws_cdk.aws_sqs/Queue.html#aws_cdk.aws_sqs.Queue.grant_consume_messages -- good documentation (this is for SQS queues, just for comparison)

I stumbled upon this when researching whether `topic.grant_publish()` grants correct permissions in case of SSE (server-side encrypted) SNS topics.

Similarly, method descriptions like `grant_subscribe()`, `add_subscription()` would benefit from more details -- what exactly these methods generate in the final CloudFormation template.

### Links

https://docs.aws.amazon.com/cdk/api/v2/python/aws_cdk.aws_sns/Topic.html

Contributor guide

Open the contributing guide

Research direction

Start with the linked aws_cdk.aws_sns.Topic.html page and compare its grant_publish, grant_subscribe, and add_subscription descriptions with the SQS Queue.grant_consume_messages documentation. Done means the SNS method documentation explains the permissions or CloudFormation effects it produces, including the SSE case raised in the issue.

Written by the indexing model from the issue text.

Assessment

Tech stack
aws
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.