"Comprehensive documentation" has missing sections
Nobody has claimed this yet.
Assessment
- Difficulty
- 5/5
- Estimated time
- Over a week
- Newbie friendliness
- 25/100
- Issue type
- Documentation
- Clarity
- Mostly clear
- Activity status
- Stale
- Tech stack
- clojure
- Domain
- documentation
Research direction
Start by locating the Tick documentation sections listed in the issue, especially sections 4.6 through 10.9, and review the existing Tick Reference entries. Inventory missing text, TODOs, unclear API explanations, and outdated references before proposing a scope. Done means the selected sections are complete, consistent with Tick 1.0, and the documented API is up to date.
Written by the indexing model from the issue text.
Description
Now that Tick has been bumped to version 1.0, it seems like it would be good to finish out the documentation.
Notably, these sections need some love:
- 4.6 Comparison - no text
- 4.7 Modification - no text
- 4.8 Truncation - no text
- 5.2 Derivation - has a bullet about adding durations to durations, but no examples or other guidance
- 5.3 Comparison - seems pretty short, but might be OK. Appears that
<=got converted to a left-facing arrow - 5.4 Misc - has "TODO" markers
- 6.2 Derivation - makes the statement "Just like times and dates, you can time-shift clocks forward and backward using the >> and << functions respectively," but this is the first time that
<<and>>have been mentioned in the document. - 6.3 Mutable Clocks - needs work. In section 6.0 the document says, "In tick, clocks are used for getting the current time, in a given time-zone. You should prefer using clocks to making direct calls to (System/currentTimeMillis), because this then allows you and others to plugin alternative clocks, perhaps for testing purposes," but then in 6.3 it says "Tick does not provide that because there is already Mock Clock," which is confusing. Does Tick want to solve this problem or not? If not, what's the purpose of Tick's Clock support?
- 6.4 Comparison - no text
- 6.5 Atomic Clocks? - Why the "?" in the section title? That said, it's not clear why this functionality exists and this isn't really explained in the text. Is there no other way to get the value out of a clock other than having it be storied in a special Tick atom? Why does it have to be stored in an atom instead of just calling a function (perhaps
deref/@) on the clock itself? Is there some sort of atomicity guarantee that a Tick atom brings to the party? If so, what is it? Since clocks are just read (shifting a clock creates another clock, right?), then what is the point of having the atom? If I want a clock in an atom, can't I just store a clock in a regular Clojure atom? - 6.6 Substitution - So,
t/with-clockallows you to set the default clock for all the other Tick functions? If so, perhaps say that explicitly. What set of functions does it apply to and which not? - 7 Intervals - are intervals still alpha given that Tick is version 1.0? Does the namespace need to be updated to remove the
alphapart of the name? If this has already been done, then the documentation needs to be updated to reflect it. If there is more to do on intervals, what is missing and what timeframe is it targeted for? Something that remains in "alpha" state for a long time makes the project feel like it's been abandoned (sometimes Clojure Spec feels the same way for the same reason). Since intervals seem to be some of Tick's primary value-add beyond the raw time primitives provides bycljc-time, it would be good to have them be solid and finished, not in some quasi 1.0-by-still-alpha state. - 7.4 Collections - seems like it wants to discuss something interesting but just doesn't complete the thought.
- 7.5 Demonstration - no text
- 8.0 - no text
- 8.1 - no text
- 8.2 - no text
- 8.3 - no text
- 9.0 - seems incomplete
- 10.8 Miscellaneous - need to find a home for these examples
- 10.9 Tick Reference - this section is great and helpful, but it feels like perhaps it could be replaced by another automated system (e.g., Codox). This wouldn't show the live examples, which are useful and that would be a loss, but it would make sure that all the API functions were listed and up to date. E.g., right now, I think it's missing
min-keyandmax-key, right? There may be others, but I noticed those. Perhaps just adding those would be easiest for now.
- Dominant language
- Clojure
- Stars
- 646
- Forks
- 61
- Avg merge
- 17h 42m
- Merged PRs (30d)
- 1
Getting set up
- No Dockerfile or Docker Compose file
- No pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from juxt/tick
-
Difficulty 1/5 Under an hour Newbie friendliness 72/100
-
help wanted
Difficulty 3/5 1-2 days Newbie friendliness 35/100
-
interval-calculus
Difficulty 2/5 1-3 hours Newbie friendliness 48/100
-
interval-calculus
Difficulty 2/5 1-3 hours Newbie friendliness 45/100
-
t/concur failsMay be free again @malcolmsparks claimed this 2574 days ago, and no pull request is open. Openinterval-calculus
Similar issues
-
.Team/Graphy
Difficulty 2/5 1-3 hours Newbie friendliness 74/100
metabase/metabase#87741 · 1 comment ·
Maintainers usually reply within 1 day
-
Accumulator with a false initial value does not propagate it again after all facts are retractedPossibly taken @0z5a claimed this 1 day ago. Open
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
oracle-samples/clara-rules#517 ·
-
internal IOP tokens no changelog no qa
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
Maintainers usually reply within 1 day
-
Misleading WARNING "Failed to find resource type wavc, couldn't enable for streaming" when the WAVOpenbug triage
Difficulty 2/5 1-3 hours Newbie friendliness 67/100
Maintainers usually reply within 1 day
-
flaky
Difficulty 2/5 1-3 hours Newbie friendliness 66/100
Maintainers usually reply within 1 day