Make API Documentation More User Friendly

[david-clark-1043]

CL API Docs Review

I reached out to @mlissner via email for something to help with, and he pointed me to cleaning up the API docs as something that is not being actively worked on. I have done some preliminary research on some other open source projects and their docs to compare. This is a summary of some of those ideas. These ideas can, and should, be split out into individual issues for work, but I figured putting it all in one to start might be useful to get some high-level ideas flowing.

Problem Links to Other Docs Images for Comparison Ideas

• Pagination
• Whitespace and Spacing
• Table of Contents Placement
• Table of Contents Nesting
• Getting Started Content
• Docs Project Structure

Conclusion

Problem

The current docs are a single page, and (no offense) a little unwieldy. Making the docs more user friendly makes people more likely to use and support the project. More people using it means more great solutions for legal professionals that people seeking legal advice could greatly benefit from.

Other Examples

Here is a table of other example docs and their source code. React, Django, and Express also have at least a short guide for contributing to the docs specifically. Bootstrap less so. Bootstrap also includes its docs in the main project similar to CL, while the others have dedicated separate projects (See Point 5)

Docs	Repo	Guides	Additional Info
React Docs	React Docs Repo	React Contributing to the Docs	N/A
Bootstrap Docs	Bootstrap Docs Repo	Bootstrap Docs Section of Readme	Seems to use Hugo
Django Docs	Django Docs Repo	Django Contributing to the Docs	Appears to use Read the Docs and Sphinx
Express Docs	Express Docs Repo	Express Contributing to the Docs	N/A

Observations

Looking at the other docs, there are some main differences that stand out. I've highlighted 4 key differences between CL and others with red numbering. Multi-page vs Single-Page structure is also discussed below, but isn't highlighted in the images. A separate repo for the docs is also discussed as point 5, but is not reflected in the images.

CourtListener

React

Express

---

Pagination

• Currently Single Page
• React, Django, Bootstrap have multi-page structure
• Express has single page, but incorporates some of the points below to mimic multi-page

I am not knowledgeable enough on UX design to make a judgment call on which is better. However, I would observe that the use of a static view Table of Contents with collapsing/expanding nesting (Points 2 and 3 below) is maybe a best of both worlds solution. This is what Express Docs uses. The dedicated TOC lets users jump around the page as if it were different pages, but the user can also scroll up and down to find conceptually related information easy without having to click to a new page every time.

---

Point 1 - Whitespace and Spacing

• Less whitespace means more space for docs content
• More vertical spacing makes the docs content more readable
• Note: white-space observations obviously depend on screen size

CL has a lot more whitespace than the multi-page docs, but Express also has a great deal of whitespace. Less horizontal whitespace means more content, while more vertical whitespace means the text is easier to read. You can see from the above pictures that React's content is much less dense, which is easier to read and understand.

---

Point 2 - Table of Contents Placement

• TOC that stays in user view allows for easier navigation
• Back to Top links help prevent the user from getting lost in the content, e.g Back to Top (intradocument linking functionality doesn't seem to work in GitHub issues)

You can't see the functionality in the images, but the other docs have a dedicated sidebar of the Table of Contents that is always in the user's view. CL has a sidebar TOC, but as a user scrolls down the page the TOC stays at the top and quickly moves out of view. The always-in-view version seems like it is much easier to navigate around the docs. Putting the TOC in a view that sticks to the user's view can still be used with a single-page structure. Express uses this structure with a single-page render.

Currently, if a person clicks a link in the table of contents or scrolls down the page, they may feel lost in the text. Including a link in each section that directs the user back to the TOC may help prevent getting lost.

---

Point 3 - Table of Contents Nesting

• TOC is currently static resulting in a large nested view
• Other docs allow for collapsing and expanding nested sections making the TOC more digestible

I don't think this point needs a lot more commentary explanation. See the images above, and check out the sites to see how the functionality differs.

---

Point 4 - Getting Started Content

• Other docs have an outline of links to other parts
• Less is more

Similar to Point 1, the other docs take a less content dense approach to the Getting Started page. A list of links to introductory material allows the user to jump to wherever they need to go to start out and doesn't overwhelm with information all at once. Express even has the Getting Started in a completely separate page structure than the general API reference.

A few introductory walkthroughs might also be useful here. Previously discussed in #1377.

---

Point 5 - Docs Project Structure

• Separating the docs repo more allows for editing it without breaking the rest of the project

Another difference is that React, Django, and Express have individual repos for their docs vs the main product. The docs for CL live in the project itself at courtlistener/cl/api/templates/rest-docs-vlatest.html. Moving that to its own folder in the project might be useful, especially if pagination is introduced because then there will be a lot more code in many files involved and putting that all in .../templates would be messy.

It also might be useful to highlight the docs on the main readme as something to contribute to such as the React, Django, and Express contributing to the docs guides. The main readme links to a dev guide, but it does not address contributing to the docs.

Conclusion

If you have other ideas feel free to add a comment. Discussion doesn't have to be limited to the points above. Let me know what you think about these comparisons!

[mlissner]

Oops, didn't mean to close...larger comment in the works in a moment....

[mlissner]

This is a great analysis, and I agree with most of your points. Thank you for doing this.

Going through things a bit...

1. I agree more vertical white space would be good. It's very dense. This would make the page longer though, and it's already very long.

2. A sticky, collapsible TOC would certainly help, I agree. This implies that we would have to move the other things below the TOC somewhere else. I'm not sure where.

3. I think a getting started page or tutorial would be great.

4. Moving the docs to a static site of its own wouldn't be terrible and is probably a decent idea. We could host it at a subdomain and that'd probably work fine. We use NextJS for free.law, so I think I'd advocate for using that, but it's a lot of work. If we did this, we'd have to think about the neat feature we currently have that the code blocks have your API token in them if you're logged in. We couldn't easily do that in a static site, though nextJS probably has a trick for doing that if we make an API to get a person's API key.

   If doing a new nextjs project is too much work, a different idea could be to move the docs into free.law somehow, but I'm not sure that really makes sense.

   If we do do something like this, a separate and developing situation is that we need more help pages. We have a few and they live under /help/whatever/. Maybe launching docs.courtlistener.com is a good idea and it could have both help pages and API docs (scope creep alert!).

Other thoughts

1. I think a larger font would help too.

2. If we do go with a separate site for this, and make the whitespace bigger, and add a "get started" page, I think all of that together would make a pretty strong case for adding multiple pages to the API docs. What I like about the single page is you know the thing you read is always on the page you're on. What I don't like is that the one page gets huge.

[flooie]

I’m a fan of the design of fellow Django open data website open states.org. Just my two cents

https://docs.openstates.org/

[mlissner]

You can definitely tell in an instant that it has the je ne sais quoi that we lack.

[flooie]

I think we have a certain charm.

[david-clark-1043]

I’m a fan of the design of fellow Django open data website open states.org. Just my two cents

https://docs.openstates.org/

I didn't know about this one. That's a good example!

4. Moving the docs to a static site of its own wouldn't be terrible and is probably a decent idea. We could host it at a subdomain and that'd probably work fine. We use NextJS for free.law, so I think I'd advocate for using that, but it's a lot of work. If we did this, we'd have to think about the neat feature we currently have that the code blocks have your API token in them if you're logged in. We couldn't easily do that in a static site, though nextJS probably has a trick for doing that if we make an API to get a person's API key.
   If doing a new nextjs project is too much work, a different idea could be to move the docs into free.law somehow, but I'm not sure that really makes sense.
   If we do do something like this, a separate and developing situation is that we need more help pages. We have a few and they live under /help/whatever/. Maybe launching docs.courtlistener.com is a good idea and it could have both help pages and API docs (scope creep alert!).

This does seem like too much. Also, I didn't see that there are /help pages as well. In fact, looking around the main site, I am not seeing the user path to get to the /help pages. Maybe a linking structure like this whose root lives on the main nav bar would be helpful

Guides (clickable link on the nav bar)
|__ Guides Page
    |__ FAQ (current faq page)
    |__ Site Help (current /help files)
        |__ Current Site Help Page 1
        | . . .
    |__ API Docs
        |__ API Tutorials (incl. Getting Started)
        |__ API Reference (current /rest-info)

To be clear, not saying the url structure should be nested, just trying to represent where links could be located and where they would be going. From this structure the only pages to add would be the overall Guides page, a base API docs page, and any tutorials to be added.

Looking at how the pages are generated from the /templates folder, I think the folder's contents could be organized in a logical nested fashion so /templates doesn't get too cumbersome. Unless a flat /templates structure is preferred of course.

Thanks for the feedback! I'll try to get a development environment spun up this week and poke around to assess how difficult some of these ideas would be to implement.

I think we have a certain charm.

For sure!

[mlissner]

Hey, just thought I'd check in here. @david-clark-1043, is this still something you might have time to help with?

[david-clark-1043]

Hi @mlissner, Yes, I can work on this. I got busy with the end of school and some traveling. I can have something on the collapsable TOC by next week. Would you be opposed to moving the information currently located beneath the TOC into the main column? I think it will still be easy to find if those blocks are added to the TOC and with it being collapsable and pinned, they wouldn't get lost.

[mlissner]

I can have something on the collapsable TOC by next week.

Awesome!

Would you be opposed to moving the information currently located beneath the TOC into the main column?

Not opposed, no. I think that could totally make sense. I could also see some of those just converted into references in the docs so the docs pages themselves aren't so damned long. For example, the change log seems like enough info to deserve its own page, and the jurisdictions already have a link here: https://www.courtlistener.com/api/jurisdictions/

[david-clark-1043]

Hi @mlissner, I'm ready to push a branch that changes the TOC to have collapsible elements, but it says I don't have contributor access. I saw in the developer guide, there's maybe something I need to sign? Let me know what I need to do.
Example of work:

Collapsed

Expanded

[david-clark-1043]

To be clear, I got:

ERROR: Permission to freelawproject/courtlistener.git denied to david-clark-1043.
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.

I'm using a secondary WSL instance on my computer to work on this project, so if that's a SSH key issue on my end, let me know, and I'll make another.

[flooie]

we have a contributor bot that I thought was triggered whenever a PR was opened by someone new. How are you trying to push your changes?

[david-clark-1043]

In my terminal

git branch -b jdc-api-docs
[made my changes]
git add --all [edits were in two files]
git commit -m "[commit message]"
git push origin jdc-api-docs

[flooie]

I think the process for new contributors, is to create the branch on a fork you control and then create a PR from that.

I believe we use

https://github.com/cla-assistant/cla-assistant

which seems to require a PR.

[david-clark-1043]

Ah, that makes perfect sense!

[mlissner]

If you want to toss a tweak to the contributor guide with this info into the PR, that might help in the future.

[mlissner]

Was just thinking about this again b/c I noticed the new TOC was looking good. @david-clark-1043, do you have plans for next steps?

[david-clark-1043]

@mlissner Hey! I've been busy with a vacation, then new job, then moving, but I should have time to work on this some over the next month or so. Next steps I think are:

• Reorganizing the sections currently under the TOC to the main section. Fairly simple, just need to move them to a different part of the file.
• Getting the TOC to scroll with the page. I fiddled with this some already, but it wasn't super straightforward.
  • Alt: reorganize into multiple, shorter pages.

I also noticed on mobile (iOS safari at least) that the TOC doesn't really show up, but I am not sure if you are concentrating on making this mobile friendly. The TOC shows up at the bottom of the page, and I don't think that's because of anything I touched. The nav links within the page also don't seem to work right on mobile.

[mlissner]

Great to have you back on this! I hope your vacation was great. :)

Sorry, I forget what this refers to:

Reorganizing the sections currently under the TOC to the main section. Fairly simple, just need to move them to a different part of the file.

This will be a really nice improvement.

Getting the TOC to scroll with the page.

I'm not sure how much we care about mobile. Maybe we could survey a few other sites to see how they handle it, but frankly, nobody is doing dev on their cell phone, so...it's probably fine to ignore this.

One other thing to throw in the hopper, in case it affects your thinking. In issue #2176, we plan to write webhook documentation. All else being equal, we'd toss that into the API docs, but I raise it here because it feels like one more instance where breaking things into a couple different pages might be smart.

Thanks for sticking with this!

[david-clark-1043]

Reorganizing the sections currently under the TOC to the main section. Fairly simple, just need to move them to a different part of the file.

If we can get the TOC to follow the user around sticky-like, then the sections currently beneath the TOC should be moved to the main column of content.

[mlissner]

Ah, yes, of course! Totally makes sense.

[david-clark-1043]

@mlissner getting this error when trying to run npm run dev. Thought I updated my branch correctly, so not sure what the issue is.

> [email protected] dev
> ./node_modules/webpack-dev-server/bin/webpack-dev-server.js --hot

The command moved into a separate package: @webpack-cli/serve
Would you like to install serve? (That will run npm install -D @webpack-cli/serve) (yes/NO) :

No does nothing. Trying yes results in this error.

npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR!
npm ERR! While resolving: [email protected]
npm ERR! Found: [email protected]
npm ERR! node_modules/webpack-cli
npm ERR!   dev webpack-cli@"^3.3.12" from the root project
npm ERR!
npm ERR! Could not resolve dependency:
npm ERR! peer webpack-cli@"4.x.x" from @webpack-cli/[email protected]
npm ERR! node_modules/@webpack-cli/serve
npm ERR!   dev @webpack-cli/serve@"*" from the root project
npm ERR!
npm ERR! Fix the upstream dependency conflict, or retry
npm ERR! this command with --force, or --legacy-peer-deps
npm ERR! to accept an incorrect (and potentially broken) dependency resolution.
npm ERR!
npm ERR! See /home/david/.npm/eresolve-report.txt for a full report.

npm ERR! A complete log of this run can be found in:
npm ERR!     /home/david/.npm/_logs/2022-09-11T20_24_59_739Z-debug-0.log
undefined

[mlissner]

Well, that's dumb, but whatever, we'll get it fixed next time we work on react stuff. In the meantime, I don't think this affects you one way or another.

[david-clark-1043]

Ah, well, I can't load up a local dev environment to test changing the UI stuff around.

[mlissner]

Really? I don't think you need npm for the part of the system you're working on? What error are you getting? Honestly, I rarely start npm most of the time.

[flooie]

I was thinking the same thing

[dschnelldavis]

Hi, I'm picking up this project. I've read all the analysis above and agree with the basic direction so far. So here's what I'm planning:

1. Move REST API TOC menu from left to right, so it matches all the other help pages on the site.

2. Move all other REST API items in the left column to the bottom of the main section.

3. Add additional REST API TOC links for new items in main section.

4. Change REST API "Available Jurisdictions" and "API Change Log" so they link to other pages.

5. Make all help TOC menus sticky, so they stay on the page when scrolling down.

6. Ask for input on other formatting changes to improve help pages.

   • Increase font size and/or vertical white space?
   • Add breadcrumbs to make it ease to navigate between all help pages?
   • Is there a logical way to break the long REST API help page into multiple pages?

7. Move on to creating tutorials/examples for the API

What do you think?

[mlissner]

That all sounds solid. I think for item 4, we should look for opportunities to link to those pages beyond just in the TOC, like in the paragraphs themselves. I think just having a link in the TOC won't be enough for them to be found.

The rest sounds really good. I assume you'll use the existing documentation templates to build these pages?

[dschnelldavis]

I was planning to make the REST API help page look and act like the other help pages, for as consistent a user experience as possible. Do we have specific templates to use for help pages? If so, I'll be glad to use them.

[mlissner]

Yeah, if you pull up any of the other help templates, they should be using the same base.