uif icon indicating copy to clipboard operation
uif copied to clipboard

Review and improve docs for nested packages

Open vostrik opened this issue 2 years ago • 1 comments

It is more useful to get quick start information in each package README file:

  • [ ] components-v6
  • [ ] runtime
  • [ ] ui-builder
  • [ ] dev-tools

vostrik avatar Jul 04 '23 18:07 vostrik

Hi!

Spend some time reviewing docs for kl-dev-tools and can suggest improvements on issues below:

Line 26: suggestion: Seems like it's possible to use ENV variables to define tsconfigRootDir and fallback to __dirname if nothing found. My idea based on the assumption that this is provided as package. IMO – packages might not be changed based from proj to proj, so defining env may bring some good changes.

Line 34: typo: extra space after the header, break markdown.

Line 36: suggestion: it would be great to add peerDependenciesMeta field for those on this requirements.

Line 48: issue: it's hard to understand what is 'shared package' in this context and why one may add it. This topic definitely needs improvement. Also it seems like both sections (see link above) are similar to each other at first sight. As far as I understood – shared config is more like an internal ability to expand package, but not applicable for open-source solution. However, config extension is the section one may want to publish. Definitely need some discussion on this topic.

Line 64: question: this one has no any description on why one should use this script. IMO, it can be done as a binary with 'post-install' script for example with user prompt on version? But this is far away from the docs problems. :)

Line 72: question: similar question as the previous point: maybe it's possible to use some kind of 'setup-scripts' to make less user interactions and improve DevExp?

– General: nitpick: README lacks description about all the using configs (take a look – a lot of sections on ESLint, but almost nothing on jest / ts / babel). Hard to understand why project even needs this package. Something like an abstract in the beginning will do.

Therefore, I would like to make some cleaning on this part of docs. I would like to know, what exactly can be changed and what should stay as is so I could propose changes for you to review.

Best wishes, Mike

mikegsrv avatar Jul 24 '23 08:07 mikegsrv