stroom:format-date() documentation needs revamp
- Dominant language
- Shell
- Stars
- 31
- Forks
- 30
- Avg merge
- 5h 17m
- Merged PRs (30d)
- 2
Description
Using the format-date() function confusing for non-UK locations if following the Stroom Documentation examples.
TimeZone ID needs to be in long format eg Europe/London, Pacific/Auckland, Australia/Canberra. But this is not intuitive from the documentation provided.
**Change documentation to be more helpful:**
- Show working examples of all 5 arguments.
- Expected output of examples is always useful.
- Changing GMT/BST in the doco to be Europe/London
- Above 3 things would probably be OK but an example or two from other timezones would be useful
- Maybe something re timezone/offset format a bit like what is in [https://binkley.blogspot.com/2019/02/java-date-time-timezone-formats.html] . I'm not sure whether Stroom format-date() supports all these options so it would be good to know.
Also current documentation example 3 incorrect - 'GMT+1:00' should be 'GMT+0100'
**In attached documents:**
Tests 1-3 correspond to the first three examples in Stroom documentation format-date().
Tests 4-6 correspond to the Stroom unit tests.
Tests 7-12 is attempts to get it timezone working for NZ. Several issues here - The 'NZ' ID works for date/time but can't generate an offset if this is the ID. The 'NST' fails completely. I would have thought I should use NZST/NZDT for the 5th argument but that generates errors. Have to use 'Pacific/Auckland' as timezone to get things working OK



Additional info in Slack #stroom-content 15Nov21
Contributor guide
Research direction
Locate the Stroom documentation page for format-date() and compare its current examples with the attached timezone tests and the corresponding unit-test examples. Verify the supported timezone and offset formats before revising the examples. Done means all five arguments have working examples with expected output, GMT/BST uses Europe/London, timezone examples are clearer, and the GMT+0100 correction is made.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100