Updates to API documentation to make transition from docket entry -> API view more clear

[s-taube]

User reported confusion when switching from the docket entry view to the API view. They would like this information to be easier to find.

This process is easier for case law. For example, when transitioning from case law view to API view, they update the url from https://www.courtlistener.com/docket/69116157/freeman-v-giuliani/ to https://www.courtlistener.com/api/rest/v4/dockets/69116157/

User had trouble finding information on how to do this for docket entries. In the end, they needed to go from https://www.courtlistener.com/api/rest/v4/dockets/69116157/ to https://www.courtlistener.com/api/rest/v4/docket-entries/?docket=69015293 or, more narrowly https://www.courtlistener.com/api/rest/v4/docket-entries/411967648/, which they learned after landing on the PACER Data APIs page.

Attempts by the user to find the relevant information:

• https://www.courtlistener.com/help/api/rest/ a search for docket_entries has no hits, nor does entries.
  -Show the APIs button was not helpful.
• APIs heading was not broken down to a level of hierarchy that would allow useful searching.
• 'https://www.courtlistener.com/help/api/rest/recap/' has two references to "docket entries" but is unhelpful.
• the eventually found the PACER Data APIs page.

[mlissner]

One thing we could do to help with this is to tweak the sentence that says:

We have almost half a billion PACER-related objects in the RECAP Archive

So it says:

We have almost half a billion PACER-related objects in the RECAP Archive including dockets, entries, documents, parties, and attorneys.

I think that'd help if CTRL+F is the first thing the user tried.

APIs heading was not broken down to a level of hierarchy that would allow useful searching.

I'm not sure we could realistically do this without re-imagining the sidebar. It'd take a lot of space to include all the descriptions of each thing in the TOC. I'm open to re-imaginings though.

'https://www.courtlistener.com/help/api/rest/recap/' has two references to "docket entries" but is unhelpful.

Hm, this page does begin with:

Use these APIs to scrape PACER data and to upload data into CourtListener's database of federal court cases and filings.
These APIs work in conjunction with our PACER APIs and data model.

So we're not so far off the mark here, but perhaps it can be tweaked to say:

Use these APIs to scrape PACER data and to upload data into CourtListener's database of federal court cases and filings.
Once data is gathered by these APIs, our PACER APIs and data model can be used to retrieve dockets, entries, parties, and attorneys from our system.

Perhaps that would help?

[johnhawkinson]

I'm not sure we could realistically do this without re-imagining the sidebar. It'd take a lot of space to include all the descriptions of each thing in the TOC. I'm open to re-imaginings though.

It's not possible to display 3 levels of hierarchy in the TOC rather than just two?

Perhaps that would help?

My initial reaction was those proposals seem like they would make thing worse!
Upon reflection I think I'm wrong, but it's interesting to think about why I thought that.

I searched for docket entries and needed to find the PACER API page, but instead I found nothing.
Putting the words "docket entries" onto more pages that don't contain the information I want feels like a step backwards, I'll do a search and instead of getting no hits (which at least tells me I'm on the wrong page), I'll get some hits that are only indirectly relevant (not directly relevant). And perhaps worse, an external indexer might then return those pages for, e.g., a Google search for "docket entries."

But of course, if I was willing to read the returned text you propose, I would find a referral to the PACER API page.
I guess this is a constant tension in the world of indexing and and referrals and reefers.

Keanu Reeves said to shoot the hostage, which often analogize to shooting the user.

[mlissner]

It's not possible to display 3 levels of hierarchy in the TOC rather than just two?

Maybe. I've played with it, and it gets junky really fast. Probably with a careful design it could work, but whenever I've tried you gain the third level, but the whole thing becomes sort of too long to bother reading.

[johnhawkinson]

but the whole thing becomes sort of too long to bother reading.

I admit, I was coming at it from the perspective of search, not reading.

I suppose having collapsed hierarchy levels (via the disclosure triangles that look like plus signs) that can be found via Cmd/Ctrl+F searching is perhaps "not a thing."

[mlissner]

I suppose having collapsed hierarchy levels (via the disclosure triangles that look like plus signs) that can be found via Cmd/Ctrl+F searching is perhaps "not a thing."

Yeah, I fear not, but my other solution above (putting keywords elsewhere on the page) seems like it'd be a step in the right direction.