Skip to content

Documentation refresh: fix README, update per-library docs, add getting-started examples #14157

@droshev

Description

@droshev

Summary

Refresh and update general documentation across the fundamental-ngx repo. The docs are already mature (CLAUDE.md, agent guides, MCP server docs are excellent), but the README and per-library READMEs have issues that need cleanup.

1. Fix the top-level README

  • Duplicate MCP section — "AI Integration (MCP Server)" appears twice (lines 23-62 and lines 97-135) with slightly different text. Consolidate into one.
  • Broken NEW_COMPONENT.md link — Contributing section links to NEW_COMPONENT.md which does not exist in the repo. Either create it or point to the wiki.
  • Section numbering artifact## <a name="2"></a>2. Requirements appears mid-page with an anchor tag, breaking the flow. Clean up.
  • No Hello World — Installation shows ng add and two import lines, but no working example. Add a minimal "create a button and a form field" snippet that someone can paste into an Angular component.
  • Package tables split awkwardly — Core Libraries table is followed by the first MCP section, then UI5/Supporting/Domain tables appear after. Reorder so all package tables are together.

2. Update per-library READMEs

Several library READMEs are stubs:

Library Lines Issue
libs/datetime-adapter/README.md 28 Minimal — no usage example
libs/moment-adapter/README.md 27 Minimal — no usage example, should mention it's legacy
libs/ui5-webcomponents-base/README.md 34 Minimal — no description of what utilities it provides
libs/nx-plugin/README.md 18 Lists generators/executors but no usage examples
libs/webc-generator/README.md 23 Minimal — no explanation of the generation workflow

The core/platform/cdk/i18n READMEs are solid. Focus on the stubs above.

3. Create NEW_COMPONENT.md or fix the dead link

The README links to NEW_COMPONENT.md for new component creation guidance. The file doesn't exist. Either:

  • Create it with the essentials (file structure, naming, standalone defaults, testing requirements), or
  • Replace the link with a pointer to the wiki if the guide already lives there

4. Add a getting-started example

Neither the README nor the docs reference a quick "Hello World" — a minimal Angular component using @fundamental-ngx/core that someone can scaffold in 2 minutes. Add one.

5. Validate documentation with AI agents

Use AI agents as documentation testers. For each guide or README:

  • Feed it to an agent and ask it to follow the instructions
  • Where the agent fails, gets confused, or produces wrong output — the docs are weak
  • Where the agent succeeds without external help — the docs are sufficient

Specifically:

  • Test the Hello World / getting-started example — can an agent scaffold a working app from the README alone?
  • Test each per-library README — can an agent correctly install, import, and use the library from its README?
  • Test NEW_COMPONENT.md (once created) — can an agent create a valid new component following the guide?
  • Document every failure point — each one becomes a doc fix

Acceptance Criteria

  • Duplicate MCP section consolidated into one
  • Section numbering artifact cleaned up
  • Package tables reordered logically
  • Hello World / getting-started example added to README
  • NEW_COMPONENT.md created or dead link fixed
  • Stub library READMEs updated with descriptions and usage examples
  • No dead links in README or CONTRIBUTING.md
  • All new/updated docs validated by running them through an AI agent and fixing failures

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions