gchq / gchq/stroom-docs

stroom:format-date() documentation needs revamp

Open
#61 2 comments 0 reactions 0 assignees View on GitHub
bug
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
![TimeZone Tests](https://user-images.githubusercontent.com/51952808/142709638-7f4b9102-f756-4413-9970-4cf3262f3dec.png)
![TimeZone Tests - Output](https://user-images.githubusercontent.com/51952808/142709642-012888cf-5cfb-4fd4-82df-b2eb347b5a49.png)
![FormatDate Translation Errors](https://user-images.githubusercontent.com/51952808/142709644-3929ea8a-5d1c-4f59-83ba-3ff5001b593a.png)

Additional info in Slack #stroom-content 15Nov21

Contributor guide

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.