Where is the documentation?

[fresheneesz]

If you go to the java docs you're left with 0 indication where to start - just a jumble of classpaths. Clicking on any of those 3 main packages is just as bad - no indication of where to go. And the website has no guide at all, just some marketing info and links to the java docs.

The javadocs by themselves are not documentation - they're a glossary. This project needs full well organized docs that put some effort into describing how to use Truth in a way that makes it easy to learn and to refer to later. It should take me 10 seconds to figure out what operators assertThat has and what other major constructs Truth provides. Going to the javadocs and seeing 100 classes organized alphabetically does nothing to help teach me how this system works or can be used.

So how about some actual documentation?

[ronshapiro]

Is google.github.io/truth what you're looking for?

On Tue, Aug 14, 2018 at 7:35 PM fresheneesz [email protected] wrote:

If you go to the java docs https://google.github.io/truth/api/0.42/ you're left with 0 indication where to start - just a jumble of classpaths. Clicking on any of those 3 main packages is just as bad - no indication of where to go. And the website has no guide at all, just some marketing info and links to the java docs.

The javadocs by themselves are not documentation - they're a glossary. This project needs full well organized docs that put some effort into describing how to use Truth in a way that makes it easy to learn and to refer to later. It should take me 10 seconds to figure out what operators assertThat has and what other major constructs Truth provides. Going to the javadocs and seeing 100 classes organized alphabetically does nothing to help teach me how this system works or can be used.

So how about some actual documentation?

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/google/truth/issues/485, or mute the thread https://github.com/notifications/unsubscribe-auth/AAwY3aBSqtRyWwN2SaWS4SvKN7Zk94qPks5uQ16wgaJpZM4V9VZt .

[fresheneesz]

I don't think so. That's what i was referring to as "the website". Is there anywhere on there that I'm missing that gives a high level overview of what Truth can do, what types of structures it contains, and starting points for how to find out how to use Truth?

[ronshapiro]

Do the links there not give you what you need? It has examples further down, as well as if you traverse the tabs.

[cpovirk]

There are some things we should do here -- which might or might not have helped in your particular case, so further ideas are welcome:

• In addition to the heading "What is Truth?" https://github.com/google/truth could have another heading "How do I get started?" And perhaps "Read more at the main website" could include the word "docs" somewhere.

• package-info files could link back to http://google.github.io/truth/, and so could classes like Subject -- maybe all classes.

• https://github.com/google/truth should also someday get a usage example, probably with example failure message.

[fresheneesz]

@ronshapiro Examples are just supplementary. A couple examples aren't documentation. Documentation should do all of the following:

1. Tell you how the package works at a high level, including concepts central to effectively using the package.
2. Give you information about every pieces of functionality in the system. If you have to look at the source to figure out how to use something, it isn't documented.
3. Organize the methods/classes/etc in conceptual groupings that make it easier to understand the functionality the system provides and how they fit together.
4. Make the boundaries of the API clear. It should be very clear which pages need to be read to have a full understanding of the API. And after reading through and understanding all the documentation, it should be very clear that there is no more left to read.
5. Be easy to skim and use as a reference. Most people don't read documentation from end to end - they skim for the information they need right now. Whether this is how to get started, what functionality the package contains, or specifics on a particular method, it should be clear how to get to the information you need.

I don't see information like that anywhere. Does any of those links tell you all of the predicates you can call off of assertThat() in an understandable way? There's the Known Types page (should be renamed to "Supported Types") that maybe tells you this information if you know what its telling you. But nothing tells you that these classes are the types returned from assertThat() and its certainly not organized in any easy to digest way. There is massive amounts of extraneous and duplicative information in each of those javadocs. Almost all of the information in the javadocs is unhelpful. This is one major reason why javadocs make terrible documentation - they're not organized based on the concepts of the package.

Like the entire "Arrays" section of that page should be written to highlight the 100% symmetry between all those classes. Every one of those classes has the same 4 methods that do the same conceptual thing. Why link to 9 separate javadoc pages and make your reader try to puzzle out this symmetry themselves? Literally that 9 pages of documentation can be summarized like this:

assertThat with Arrays

Array types have the following assertions:

• isEmpty() - Fails if the array is not empty (i.e. array.length != 0).
• isNotEmpty() - Fails if the array is empty (i.e. array.length == 0).
• hasLength(int length) - Fails if the array does not have the given length.

To test the arrays as if they were Iterables:

• asList() - Returns an Iterable subject.

Supported array types: Object[], boolean[], byte[], char[], double[], float[], int[], long[], and short[].

Isn't that way easier to understand than 9 pages with almost identical information? This is possibly the most egregious example, but the same concept holds for the rest. Many objects have a contains method, many objects have an isEqualTo method. There is a ton of conceptual symmetry in Truth's design, and that symmetry should be used to make the documentation easy to understand.

Honestly, just renaming the "Known Types" section to "Documentation" and adding some information saying that assertThat returns one of the following objects depending on the passed in type would go a long way to making things a lot clearer. Right now there is nothing that tells you why there is a "known types" page, what those types mean, or how to obtain the classes each type links to. I'm no expert on Truth so I don't know if there's more to it than assertThat() since nothing in the documentation makes it clear if assertThat() and assertWithMessage() are the only two important entrypoints to using Truth.

So the information might all be there (maybe), but its not written in an easily understandable format. For a library like this, there should probably just be a single page that describes all the methods available in the package.