Repository navigation
Answer what first-time users got stuck on - #9
Merged
Merged
Conversation
Fifteen simulated first-time users worked through the README and go doc. Most missed the imports and misread "one option per call", both lost in the last trim. Usage is a complete program again, with a plainer sentence about what With covers. The README and docs now also show a named duration type with a format, a struct that keeps time.Duration fields when others encode it, joining with existing marshalers, a format from an environment variable, the error texts people search for, rollout order when migrating, and that ISO8601 reads lower case and a decimal comma. The Java example is the common "PT-30S", and the package doc lists ErrWrongType among the causes.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes from a simulation: 15 Haiku agents each played a first-time user with one goal, read only the README and
go doc, and wrote notes on where they got stuck.Undoing too much trimming in #8 (the most common complaints)
encoding/json/v2). I ran it as written.Gaps
type TTL time.Duration, and a struct that keepstime.Durationfields when others encode it:two new tested examples (
ExampleWith_namedType,ExampleWith_structWithoutOptions), the first also in the README.Valid()andFormats().no default representation,calendar units have no fixed length. Malformed JSONis a
jsontext.SyntacticError.Milliwrites 1.5ms as1.5; noGOEXPERIMENTneeded.ISO8601reads lower case and a decimal comma, now said in public docs; the Java example is the commonPT-30S.This changes only the example, not whether Java's form is accepted.
doc.golisted the causes withoutErrWrongType.Not done: putting
AcceptDaysinto the error message itself. Error messages can reach API clients, which should notread an option name, so the README quotes the message next to the fix instead.
The README grows from 197 to 256 lines, mostly the complete Usage program. pkg.go.dev shows it only after a release.