Several Docs Missing in Repo, but Referenced and Published on Live AWS User Guide? #428
Comments
|
Hey, thanks for bringing up the issue! Your script sounds cool. I'd be interested to know whether you also generate the content portions (outside of the structures and parameters). We also auto-generate our documentation from the CFN resource specification. As such there is a slight delay before we update our GitHub docs repo with the latest supported resources and properties (see the Release History here: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/ReleaseHistory.html). We try to keep the delay as short as possible so there's very little drift. Having said all that, we'll double check your diff to see if these all fall into that category of recently added resources/properties. Thanks for pointing this out! |
Ah, cool, that helps explain. I completely overlooked the Release History page! I'll definitely have some comparison lookups in the future to see if missing stuff is likeley new stuff on delay. I should have also said this is using the latest us-west-2 cfn resource spec file, as I haven't included eval of the other regions. I do actually pull other content to add into my code, for documentation purposes, such as resource and parameter descriptions. The current example is where I am using CFN resource documentation to generate resource-specific PowerShell Core functions. Here is an example output of one: function New-AWSCFNApiGatewayAccount {
<#
.Synopsis
The AWS::ApiGateway::Account resource specifies the IAM role that Amazon API Gateway uses to write API logs to Amazon CloudWatch Logs.
.DESCRIPTION
The AWS::ApiGateway::Account resource specifies the IAM role that Amazon API Gateway uses to write API logs to Amazon CloudWatch Logs.
**Important**
If an API Gateway resource has never been created in your AWS account, you must add a dependency on another API Gateway resource, such as an AWS::ApiGateway::RestApi: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html or AWS::ApiGateway::ApiKey: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-apikey.html resource.
If an API Gateway resource has been created in your AWS account, no dependency is required (even if the resource was deleted.
.PARAMETER CloudWatchRoleArn
The Amazon Resource Name (ARN of an IAM role that has write access to CloudWatch Logs in your account.
.LINK
http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-account.html
#>
[CmdletBinding()]
param(
[Parameter(Mandatory=$False)]
[String]$CloudWatchRoleArn
)
[PSCustomObject]@{
'Type' = 'AWS::ApiGateway::Account'
'Properties' = @{
'CloudWatchRoleArn' = "$CloudWatchRoleArn"
}
}
}PowerShell Core comment-based help allows for help documentation in-terminal output to look like this: With the ability to convert into JSON: It's a work in progress, but being able to simply pull this git repo, and parse the appropriate Markdown docs allows for easy built-in documentation/help generation. I'm going to be extending it to include region-specific rules/checks, so I had to build a tool that will create and manage my own reference repository as I couldn't find the spec files in any AWS github repo: ScriptAutomate/aws-cfn-resource-specs (I point this out in #4 ) Broken Documentation Links (using us-west-2 spec file as reference)Does the lag in source repo documentation replication explain these Broken
If not, I'll open a second issue in relation to the broken links. |
|
@ScriptAutomate Resource specification for
|
|
@PatMyron thanks for the info on most-populated resource specs, and I'll also be taking a look at
Looking at the release history over the past week, there haven't been any new resource specs that have been published reflecting the updates from the Aug. 29th update. Is there a similar lag time that occurs with spec json files reflecting changes referenced in release version history? For example,
I haven't done a new
Remaining stuff:
NOTE: I've created an issue in my own repository for these broken links where I am tracking these files at ScriptAutomate/aws-cfn-resource-specs: [v5.1.0] Broken Documentation Links |
|
UPDATE: I have finished some automated tooling around broken
I found a total of 17 issues. They seem to be a mix of issues around:
Here are the types of issues I've come across: BrokenDocLinks
MissingDocLinks
MissingFromAWSGitHubSourceRepo
|
|
11/11/2019 EDIT: Increased days of time in below table for latest 10/31/2019 EDIT: Increased days of time where items are still broken by another 30 days. Based on the history of this issue, and what is actually considered missing docs that aren't merely a result of the slight lag between source documentation syncs (as in, has the error existed for greater than 2 weeks, as mentioned by @AWSRandall ), these are the 14 missing or otherwise broken documentation errors spread across the three categories mentioned in the previous comment:
This table was generated from |
|
I will no longer be updating the table in the last comment. The most up-to-date documentation lookup errors can be found here, which will continue keeping results of AWS documentation audits for changes/errors/etc: It includes a list of errors that will be related to this issue. As of today, at least 10 or 13 of the documentation errors have existed for anywhere between 100 and 210 days (broken documentation links, completely missing documentation, absence of documentation link in spec file, missing in GitHub source mirror, etc.). Some additional, helpful information (but not fully updated/accurate because it's rather tedious and no longer managed), can be found here: If there are any questions, feel free to ask. |
|
I have since archived the following project: If this is of any assistance, the final generated list of broken links was last done back in January 2023, so I don't know how valid they may be anymore: |
|
Closing this issue or pull request in advance of archiving this repo. For more information about the decision to archive this repo (and others in the 'awsdocs' org), see the announcement on the AWS News Blog. |
I've been auto-generating code from CFN Resource specification files, and part of the generation runs through and automatically builds help documentation. Though, many of the source files that I would be pulling from only exist on the live user guide and not in the GitHub source documentation. Is there some kind of release strategy where documentation becomes available in the official AWS documentation before hitting the source repo here?
The text was updated successfully, but these errors were encountered: