Maintenance: review API docs & README across repo #2381
Labels
confirmed
The scope is clear, ready for implementation
documentation
Improvements or additions to documentation
internal
PRs that introduce changes in governance, tech debt and chores (linting setup, baseline, etc.)
Summary
Some of the README files in the repo could use some polishing and focus, especially the ones for the core utilities that are older. Customers finding the packages on npmjs.com want to know what the package can do and whether it can help solve their requirements, not learn about Powertools as a whole.
Likewise, customers using the API docs need to be able to get the right level of info for all the public methods, types, functions, etc. that are exported. This is not the case today and some of them are either not included in the API docs or under documented.
Since I expect this type of effort to touch several files I am breaking down the work in smaller units.
Below a list of issues to tackle this topic:
In addition to the above, before closing this issue, we should also:
typedoc.json
file at the root of the projectWhy is this needed?
So that customers finding the package on npm or using the API docs have the right level of details.
Which area does this relate to?
Other
Solution
For the README files, the structure should be similar to the one found in the JMESPath utility which is more recent, that is:
For the API Docs we should ensure that:
exports
section of thepackage.json
are referenced in theentryPoints
list of the package'styped.json
@param name description
@returns
is not present since it's inferred by TypeScriptCalculate the average
(correct) vsCalculates the average
(wrong){@link url | title} notation
@example
notation@default
Acknowledgment
Future readers
Please react with 👍 and your use case to help us understand customer demand.
The text was updated successfully, but these errors were encountered: