The Book is hardly readable

[JakkuSakura]

This book https://time-rs.github.io/book has almost nothing in it. Is it complete?

[jhpratt]

No, it's not.

[SorteKanin]

It would be helpful if the book made it clear that it is incomplete - right now the missing text seems like a bug :)

[briankung]

This deterred me from using this crate for several days trying to find the actual contents of the book. It was a lower priority so I just kept doing other things and I've only just now started to look into this in particular. I'd be happy to help document if there's a good place to start?

[jhpratt]

Incidentally I was just thinking about this last night. I think it may be preferable to inline this into crate documentation, using empty modules for hierarchy. This would make it more discoverable and more likely to be maintained once it's actually written.

If you're looking for somewhere to start, though, documenting formatting and parsing is probably the best place initially. Other than that I don't think there's a particular order that anything should be completed in.

This is, quite obviously, a low priority for me. There's development of the time crate itself, a number of RFCs that I am working on for Rust itself, and other improvements in Rust that are where I've been putting my focus. I certainly appreciate the offer to help! I assure you I will review any pull requests that are sent my way, even if they may be delayed (like the couple open now).

[laralove143]

i also think there should at least be an incomplete warning in the main page of the book and in the website https://time-rs.github.io

[egrieco]

There's a reason the US Army puts "This page intentionally left blank." in their various manuals. The book almost scared me away from this crate as well.

[jhpratt]

Everyone: I'm super busy. The website is open source. Feel free to create a pull request with the notice. Or better yet, help write some documentation 😉 Repeated comments here don't do anything.

[egrieco]

Fully understand @jhpratt. Been working on other code but I'll try to get to this in the not too distant future.

I would feel a little bit bad just adding a whole bunch of "Intentionally left blank." comments. However, now that I'm actually using the library, there are a few other code changes that might up the priority of creating a pull request.

[xy2i]

Am championning this. @jhpratt anything to keep in mind?

[jhpratt]

Not really.

[sourcefrog]

(Let me first say I absolutely understand this is maintained on a volunteer basis and this comment is posted with an intention to be useful rather than to complain.)

I also just looked at https://docs.rs/time/0.3.12/time/index.html which has no introduction to the crate but rather just begins with a list of feature flags. It makes the crate look less mature than it apparently is.

I agree that moving it into rustdoc would make it more discoverable and make the rustdoc look better, and that is probably the first thing people will find. This also does not seem like it will be such an enormous crate that it needs a separate book. Since @jhpratt says this would be acceptable in principle I might send some PRs.

[jhpratt]

No worries about tone, I fully agree!

In terms of migration to within the crate, I would prefer the book be developed in its current location first. Once it's sufficient, I can move it into this repository (possibly as a subtree, not sure).