介绍
aws有大量的文档，有时会错过标记。
最近，我遇到了两个不同的AWS文档示例，要么使我感到困惑或沮丧。
注意：
通过“令人沮丧”，我主要是在“阻碍或防止（努力，计划或欲望）”（WordWeb）的含义的“努力，计划或欲望）。
主要是。
现在，我不想作为投诉Franey遇到，但是自从我一直在documentation工作Blurry以来考虑什么使良好的技术文档好。
我认为我还没有弄清楚 ，但是我发现了两个AWS文档的特征，这些特征可能会伤害文档，也许相反的情况可以改善它。
请继续阅读两个AWS文档故障的分解以及我从那里学到的东西。
特质1：困惑
获得指向VS代码扩展的直接链接需要多少个步骤？
从lambda功能控制台页面页面，需要4个点击，读取和滚动才能到达实际VS代码扩展。
即使在AWS Toolkit for Visual Studio Code网站上，仍然有两次单击以使用直接VS代码链接到达页面（该链接折叠低）。
这是一个很长的步行路程，最终成为一个打开VS代码本身扩展的链接。
四次单击可能是一键的东西？
那真是令人困惑。
也有一些有关VS代码扩展的文档的风险。
将文档网站与读书人分开可能意味着：
- 您必须在多个位置维护文档，这可能很难同步
- 如果两个地方之一的文档不足以保持同步，则意味着文档可能足够通用，以至于
info ：我确实需要在到期的地方给予信用：VS代码扩展文档的较早版本没有打开VS代码中扩展程序的链接；单击之后，它要求我们打开VS代码并搜索扩展名。
特质2：令人沮丧
当文档不完整时，这是令人沮丧的 - 尤其是在代码示例中。
以AWS CDK's koude0为例，以此Python代码示例：
entry = "/path/to/function"
image = DockerImage.from_build(entry)
python.PythonFunction(self, "function",
entry=entry,
runtime=Runtime.PYTHON_3_8,
bundling=python.BundlingOptions(
build_args={"PIP_INDEX_URL": "https://your.index.url/simple/", "PIP_EXTRA_INDEX_URL": "https://your.extra-index.url/simple/"}
)
)
使用Pylint通过（Pyrfecter）覆盖代码，我们可以看到许多鳞片问题：
2:9: undefined name 'DockerImage'
4:1: undefined name 'python'
4:23: undefined name 'self'
6:13: undefined name 'Runtime'
7:14: undefined name 'python'
有几个缺少易于分析的导入（Runtime，DockerImage），但是python？
我在CDK Developer Guide或CDK API documentation或AWS CDK Examples中找不到。
从搜索引擎获得帮助后，我发现丢失的python导入是：
from aws_cdk import aws_lambda_python_alpha as python
和要安装的PYPI软件包是：
aws-cdk-aws-lambda-python-alpha
和self？
python.PythonFunction Call Shoud在CDK Stack中。
如果我们检查the documentation for that，我们将获得一个App和Construct的示例，但是Stack类是固定的：
from aws_cdk import App, Stack
from constructs import Construct
# imagine these stacks declare a bunch of related resources
class ControlPlane(Stack): pass
class DataPlane(Stack): pass
class Monitoring(Stack): pass
class MyService(Construct):
def __init__(self, scope: Construct, id: str, *, prod=False):
super().__init__(scope, id)
# we might use the prod argument to change how the service is configured
ControlPlane(self, "cp")
DataPlane(self, "data")
Monitoring(self, "mon")
app = App();
MyService(app, "beta")
MyService(app, "prod", prod=True)
app.synth()
至少没有绒毛错误！
对于Stack的代码示例，我去了documentation for koude8，发现了这一点：
class MyFirstStack(Stack):
def __init__(self, scope: Construct, id: str, **kwargs):
super().__init__(scope, id, **kwargs)
s3.Bucket(self, "MyFirstBucket")
和覆盖输出？
1:20: undefined name 'Stack'
3:31: undefined name 'Construct'
6:9: undefined name 's3'
我们可以从Stacks page中的代码样本中获取Stack和Construct。
so。
在检查了aws_cdk.aws_lambda_python_alpha API文档，AWS CDK开发人员指南的多个页面，GitHub示例repo和一些搜索以查找the docs for "@aws-cdk/aws-lambda-python-alpha module"（与CDK API文档分开），我们有足够的文档来使用这些新的文档（并且非常非常）有用！）Python CDK构造。
但是，男孩，我必须为此工作。
我不记得我花了一个完整的工作例子花了多少时间，我颤抖着想着花费了多少次小时。
一个完整的工作代码示例可以节省时间，我很乐意义务：
from aws_cdk import Duration, RemovalPolicy, Stack
from aws_cdk import aws_dynamodb as dynamodb
from aws_cdk import aws_lambda as lambda_
from aws_cdk import aws_lambda_event_sources as event_sources
from aws_cdk import aws_lambda_python_alpha as lambda_python
from aws_cdk.aws_lambda_python_alpha import PythonFunction
from constructs import Construct
class WorkingStack(Stack):
def __init__(self, scope: Construct, construct_id: str, **kwargs) -> None:
super().__init__(scope, construct_id, **kwargs)
# Resources
python_dependencies_layer = lambda_python.PythonLayerVersion(
self,
"PoetryLayer",
entry="./src/layer",
compatible_runtimes=[lambda_.Runtime.PYTHON_3_10],
)
dynamodb_table: dynamodb.Table = dynamodb.Table(
self,
"WorkingTable",
partition_key=dynamodb.Attribute(
name="PK", type=dynamodb.AttributeType.STRING
),
stream=dynamodb.StreamViewType.NEW_IMAGE,
sort_key=dynamodb.Attribute(name="SK", type=dynamodb.AttributeType.STRING),
removal_policy=RemovalPolicy.RETAIN,
billing_mode=dynamodb.BillingMode.PAY_PER_REQUEST,
)
# Functions
react_to_new_entries_function: PythonFunction = PythonFunction(
self,
"ReactToNewEntries",
entry="./src/functions",
index="react_to_new_entries.py",
runtime=lambda_.Runtime.PYTHON_3_10,
layers=[python_dependencies_layer],
environment={
"TABLE_NAME": dynamodb_table.table_name,
},
timeout=Duration.seconds(29),
)
# Event handling
react_to_new_entries_function.add_event_source(
event_sources.DynamoEventSource(
dynamodb_table,
starting_position=lambda_.StartingPosition.TRIM_HORIZON,
batch_size=5,
bisect_batch_on_error=True,
retry_attempts=1,
)
)
dynamodb_table.grant_read_write_data(react_to_new_entries_function)
信息：
我正在撰写另一篇文章，其中显示了一个完整的AWS CDK项目，其中键入Python。
敬请期待！
概括
文档应该产生更多的答案，而不是问题
如果您的文档需要多个其他（可能未链接的）文档来源有帮助，则存在问题。
尤其应该完成代码样本，以使使用代码轻松开始。
信息：维护完整而准确的代码样本可能很难维护和验证，这是我曾经制作的koude16的原因之一，这是在Markdown中嵌入Python代码块上运行flake8的小包装。文件。
（我认为现在我应该在johnfraney.ca上使用它。）
文档应该预测读者最有可能寻找的信息，并使得很容易找到
如果有人单击有关VS代码扩展的链接，请进行召唤以下载该扩展名dead-simple以查找。
其他信息也可能会有所帮助，尤其是对于学习新技能或概念的人，但对于有一个很好的了解的人来说，这很容易。
最后 rites 写单词
写文档很难。
而且很容易选择AWS，这不仅是因为它们具有太多的文档，而且还因为它们有维护出色文档的资源。
但是，阅读文档比编写文档要容易得多，并且抱怨文档比修复文档要容易得多。
因此，请留意使文档变得伟大和肮脏的事物，发送PRS并编写一些代码...Y。