vaadin / vaadin/docs

Hackathon 25.3: Seven documentation gaps found while building a real application on 25.3

Open
#5,975 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
AsciiDoc
Stars
38
Forks
225
Avg merge
1d 4h
Merged PRs (30d)
170

Description

Description

Each of these cost between twenty minutes and an afternoon, and each is a page that exists and does not say the thing.

Signals outside a reactive context. The rules are learnable and not written down in one place: get() only inside computed or effect, peek() anywhere, untracked when you mean it. MissingSignalUsageException teaches the first one the hard way.

@DynamicPageTitle. The annotation is named and the shape of the generator it needs is not: what interface, what the context carries, when it is called.

Grid selection with lazy data. Nothing says that the select all checkbox is unavailable, so an application discovers it by setting the visibility and watching nothing happen. See the separate issue for the API side.

Charts style properties. The page lists the CSS properties a chart honours and does not say that it honours none of them until setStyledMode(true). See the separate issue.

The dev loop CLI. The reference table is pessimistic about what enhanced class redefinition absorbs: a new field plus a new method hot swapped in under a second, where the table says restart. Being told to expect a restart makes people batch edits to save restarts that were never going to happen.

MessageList and markdown. Every AI example passes a bare new MessageList(), and every model writes markdown, so the first live answer arrives with asterisks in it. setMarkdown(true) fixes it and no example calls it.

TestBench's base class shadows assertEquals. TestBenchTestCase brings its own, with the arguments the other way round, so a JUnit assertion silently compares the wrong way. The page that introduces the base class does not mention it.

Why it matters

None of these is a defect. Together they are most of the time this application lost to the platform, which is the sort of thing a release wants to know.

Expected

A sentence or a paragraph on each page. The signals one is worth a page of its own.

Found on 25.3.0-beta1.

Contributor guide

No contributing guide indexed for this repository

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.

Research direction

Locate the documentation pages covering signals, @DynamicPageTitle, grid selection, chart styling, the dev loop CLI, MessageList, and TestBenchTestCase. Read the existing API guidance and examples first; done means each gap has accurate explanatory text, relevant examples call out required behavior, and the pages no longer imply the incorrect defaults or limitations described here.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.