Cleanup and reorganize

[samglover]

This PR makes no changes to the substance of the documentation. The most obvious changes are to the nav bar and sidebars, and the sidebar labels for many pages.

My goal was to separate the main "categories" of information in the documentation, which seem to be these:

• About the Document Assembly Line, and our documentation around processes and best practices.
• Document Assembly Line component documentation.
• API documentation/function reference.
• Docassemble documentation links.

I changed some prominent instances of "Document Assembly Line Project" and "Assembly Line Project" to simply "Document Assembly Line."

I removed the CourtFormsOnline link from the navbar and removed the View our work button from the home page. The Document Assembly Line is no longer primarily a Massachusetts court project, and those buttons seem like they would be off-putting to someone viewing the site for another jurisdiction. They feel out of place.

I also made some small layout tweaks to the home page to even up the columns.

I removed lots of commented-out code that seems unlikely to ever be used (and it's easy enough to go back and get it from past commits or the Docusaurus repo.

This is not a comprehensive update. It is a starting point that provides a framework for future updates.

[nonprofittechy]

Exhaustive list of all broken links found:

• On source page path = /docassemble-AssemblyLine-documentation/docs/framework/github_feedback: -> linking to ../#get-involved (resolved as: /docassemble-AssemblyLine-documentation/docs/)

• On source page path = /docassemble-AssemblyLine-documentation/: -> linking to /docassemble-AssemblyLine-documentation/docs

[samglover]

OK, I think I got all the broken links.

[nonprofittechy]

OK, I think I got all the broken links.

FYI to see on your local machine, npm run build

(yes all looks good now)

[samglover]

I don't disagree with anything in either of your comments, @plocket and @nonprofittechy. My plan was simply to sort the existing content into some more clearly delineated buckets, then dig into each bucket.

Let's talk about this at today's Document Assembly Line office hours and decide how to proceed. I think this is fairly high priority considering some the projects in our pipeline.

[nonprofittechy]

Two ideas about improving the API section from interrogating ChatGPT:

https://chat.openai.com/share/b931b58a-5082-4d3c-8206-cdfda580ddf1

1. We could embed the API docs into the narrative docs, it seems, with a bit of MDX.
2. We could improve the look and feel of the API docs by adding more sub-pages, and perhaps put the narrative guide contents into the API pages.

[nonprofittechy]

Other documentation reference examples:

• https://codex.wordpress.org/Main_Page
• https://docusaurus.io/docs

[samglover]

While I prepare a manual card sort, I asked ChatGPT to do one. Here are the categories it came up with:

Category 1: Getting Started Category 2: Advanced Usage Category 3: Troubleshooting and Support Category 4: Examples and Use Cases Category 5: Integration and Deployment

(I don't think this is particularly helpful.)

[samglover]

I did my own card sort, and came up with the following categories/buckets:

• How to use the software to build interviews/an interview portal
• Project management
• Best practices
• EFSP reference material
• Meta (about the DAL)

You can see my MS Planner board card sort.

[nonprofittechy]

I think we have these "tasks" from the documentation page:

These seem to go together for developers:

• Set up your environment (e.g., install Docassemble and the Assembly Line packages)
• Look up specific syntax for classes and functions
• Understand the Assembly Line features at a high level, to help you pick the right classes

These seem more aimed at potential partners or people who may not even use any Assembly Line code in the end:

• Learn about the Assembly Line and what we offer to partners, including high level information about the EFSP
• Get guidance on writing good questions for guided interviews
• Get guidance on how to project manage your guided interview project

Edit: Actually, I wonder if we should move the guidance on writing good questions and project management to the Legal Tech class? Worth raising on a Monday call.

[samglover]

I definitely think we need to reconcile the legal tech class textbook with this documentation. From the perspective of this documentation, it seems like it should be consolidated here. But I understand the class also needs a textbook and it doesn't make sense to duplicate effort.

I also think reorganizing this documentation can happen separately, but I guess it's a question of whether we're trying to make incremental improvements or overhaul the project documentation all at once.

[samglover]

@nonprofittechy Thinking on this further, I think it's definitely helpful to frame the documentation in terms of audience first, then the different things they want to do with the documentation.

[nonprofittechy]

I think your approach of starting with just reorganizing the existing content is totally right. But yeah, it will help to think ahead to the new content we might add and that our categories will make space for that content.

What about:

1. Getting started - just the installation steps. Could also have "About the Assembly Line" in this section, both the short version and more detailed high level description of what we built.
2. Reference - API docs and tutorials, could also have the "how to write good" content in this area. We might not be able to merge the API docs immediately as it will take some experimenting with the technical settings.

Alternatively, just "docs" and "api" seem to be pretty common top level categories across technical sites.

I'm okay if we end up re-organizing within each section later.

I'm open to merging some of the legal tech class Docassemble stuff here, if we can figure out how to preserve existing links. That all well predates the AL Docs and has existing links in the wild, but I'm fine to prioritize this audience.

[samglover]

I'll take another look at this PR, then, reorganize along those lines, and resubmit.

[nonprofittechy]

Clio (https://docs.developers.clio.com/api-reference/) is another interesting reference example that breaks it into 4 categories:

• Handbook
• Docs
• Guide
• API

(To be honest, this feels too vague, not sure difference between guide and docs)

[samglover]

OK, I reorganized the documentation into "Getting Started" for non-technical folks, and "Documentation" for interview builders.

There is a lot of work left to do. For example, al_general, al_document, and al_income all have two pages with lots of overlap. There isn't much consistency among pages documenting functions/modes. And I'm not thrilled with the file organization within the repo.

But this at least gets things organized, and going forward I'll tackle a page or section at a time for substantive updates and internal reorganization.