Roadmap: improve documentation, demos, and test coverage

Open
#1,148 0 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
25/100
Issue type
Documentation
Clarity
Needs clarification
Activity status
Quiet
Tech stack
angular, typescript

Research direction

Start by splitting this parent issue into a focused follow-up, beginning with README.md, CONTRIBUTING.md, or the testing strategy document. Read the relevant package areas, including @plait/core, @plait/common, @plait/draw, and @plait/mind, before choosing one task. Done means the selected documentation, demo, or test goal is completed and its stated success criteria are met.

Written by the indexing model from the issue text.

Description

documentation tracking

Background

Plait already powers real drawing and whiteboard products, including Drawnix. To make the project feel more professional, trustworthy, and contributor-friendly for the international community, we want to improve three public-facing foundations first:

  • Documentation
  • Demos and examples
  • Test coverage

This issue is the parent tracking issue. We can split the checklist into smaller follow-up issues and complete them one by one.

Goals

  • Help new users understand what Plait is, how it relates to Drawnix, and which package to use.
  • Help contributors understand the architecture, extension model, and package responsibilities.
  • Provide runnable demos that can be used as learning material, not only visual showcases.
  • Improve test coverage around public APIs, core transforms, plugin behavior, and important drawing interactions.
  • Make project quality easier to evaluate from GitHub and CI.

Documentation TODOs

  • Refresh the English README.md with clearer positioning, feature overview, package list, demo links, and development commands.
  • Explain the relationship between Plait and Drawnix.
  • Add or improve CONTRIBUTING.md with local setup, build, test, docs, and PR guidelines.
  • Add an architecture overview covering board model, element model, plugin pipeline, transforms, rendering, and framework integration.
  • Document package responsibilities and dependencies for major packages.
  • Improve the custom plugin guide with a complete plugin lifecycle example.
  • Improve API docs for board inputs, outputs, options, events, transforms, and public extension points.
  • Review existing docs for outdated content, typos, and inconsistent package names.
  • Add links from docs pages to related demos and source files.

Demo / Example TODOs

  • Add a minimal Angular board example using only the smallest useful Plait setup.
  • Add a basic mind map example.
  • Add a basic draw example for geometry, arrows, and text.
  • Add a flow example with custom nodes and custom edges.
  • Add a graph visualization example using the ForceAtlas integration.
  • Add a theme customization example.
  • Add a custom plugin example that demonstrates element creation, rendering, transforms, and tests.
  • Make demo source files easy to find from the documentation.
  • Ensure each major package has at least one runnable example.

Test Coverage TODOs

  • Define and document the testing strategy for Plait packages.
  • Classify tests by type: pure utilities, board transforms, plugin behavior, Angular components, rendering helpers, and interaction logic.
  • Add canonical testing examples for each test type.
  • Improve @plait/core coverage for board creation, selection, viewport, history, group, and z-index behavior.
  • Improve @plait/common coverage for resize, rotate, line routing, grouping, image helpers, and shared drawing utilities.
  • Improve @plait/draw coverage for geometry creation, arrow-line behavior, table behavior, clipboard behavior, and resize logic.
  • Improve @plait/mind coverage for node transforms, layout behavior, topic positioning, image/emoji behavior, and drag-and-drop detection.
  • Improve @plait/layouts, @plait/flow, and @plait/graph-viz coverage for important edge cases.
  • Add CI visibility for test coverage, such as coverage artifacts or reports.
  • Decide an initial practical coverage baseline, then raise it gradually.

Suggested order

  1. Refresh the English README.
  2. Add contribution guidelines.
  3. Write the testing strategy document.
  4. Add the first minimal Angular board demo.
  5. Add the architecture overview.
  6. Start improving coverage package by package, beginning with core, common, draw, and mind.

Success criteria

  • A new contributor can run the project and understand the package structure within 10 minutes.
  • The docs explain both usage and extension, not only internal notes.
  • Every major package has a clear documentation entry and at least one runnable example.
  • Important public APIs and interaction logic have meaningful tests.
  • CI gives maintainers and contributors a clear signal about build and test health.
Dominant language
TypeScript
Stars
703
Forks
61
PR merge metrics
No merged PRs in 30d

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from worktile/plait

All issues in worktile/plait

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.