Add interview builder pages #459

samglover · 2024-08-30T17:00:44Z

This PR adds an interview project roadmap page, deletes some outdated pages, and reorganizes the sidebar.

This is an important but incremental update. It introduces the interview project roadmap and removes outdated information (while preserving what's worthwhile from it). It leaves some work to be done—specifically incorporating the Working with Teams page into the roadmap (or more likely, splitting it up into additional child pages under Interview Projects.

This will be the final PR for this branch, which never should have been so complex. Going forward I'll try to make smaller topic branches.

commit d2239b4 Merge: c53e8f8 88a7aa6 Author: Sam Glover <sam.glover@suffolk.edu> Date: Fri Aug 9 09:44:54 2024 -0500 Merge pull request #457 from SuffolkLITLab/add_beginners_guide_pages Add beginner's guide and resources pages commit 88a7aa6 Author: samglover <sam@samglover.net> Date: Fri Aug 9 09:36:14 2024 -0500 Updates links and redirections commit 9ec128a Author: samglover <sam@samglover.net> Date: Fri Aug 9 09:35:55 2024 -0500 Add beginners guide and resources; move planning and team tips to Get Started commit c53e8f8 Merge: d2d189f 52f6f62 Author: Quinten Steenhuis <qsteenhuis@suffolk.edu> Date: Fri Aug 2 16:32:03 2024 -0400 Merge pull request #456 from SuffolkLITLab/document-translating-interview Document how to enable translations in an AssemblyLine interview commit 52f6f62 Author: Quinten Steenhuis <qsteenhuis@gmail.com> Date: Fri Aug 2 16:31:09 2024 -0400 Document how to enable translations in an AssemblyLine interview commit d2d189f Merge: ee0a270 2ed31d5 Author: Quinten Steenhuis <qsteenhuis@suffolk.edu> Date: Thu Aug 1 16:00:03 2024 -0400 Merge pull request #455 from SuffolkLITLab/pronouns Document new pronouns capability for 1st and 2nd person commit 2ed31d5 Author: Quinten Steenhuis <qsteenhuis@gmail.com> Date: Thu Aug 1 15:59:43 2024 -0400 Document new pronouns capability for 1st and 2nd person commit ee0a270 Merge: 3e8bdae 15d7a3d Author: Quinten Steenhuis <qsteenhuis@suffolk.edu> Date: Sat Jul 27 07:19:26 2024 -0400 Merge pull request #453 from SuffolkLITLab/updating-filing-codes Add more examples to e-filing integration commit 15d7a3d Author: Quinten Steenhuis <qsteenhuis@gmail.com> Date: Sat Jul 27 07:15:11 2024 -0400 Add more examples to e-filing integration commit 3e8bdae Author: samglover <sam@samglover.net> Date: Fri Jul 26 12:06:18 2024 -0500 Move CNAME commit 74de987 Merge: 63e3e07 d71dfcc Author: plocket <52798256+plocket@users.noreply.github.com> Date: Tue Jul 23 09:58:19 2024 -0400 Merge pull request #452 from SuffolkLITLab/alkiln_step_delete_interviews Add the new ALKiln "delete user interview session" feature commit d71dfcc Author: plocket <52798256+plocket@users.noreply.github.com> Date: Mon Jul 22 11:24:24 2024 -0400 Add a new ALKiln "delete user interview session" feature

This reverts commit eb4bfa6.

plocket

This looks like a big step forward! Sorry I haven't had the bandwidth to refine my comments down to the more substantive ones. I think the most relevant concerns I have is about some vagueness in certain sections of guidance and some of the material that was removed. As a whole, this does a lot of good consolidation in my opinion.

plocket · 2024-08-30T17:25:08Z

docs/get_started/assembly_line_setup.md

-## Setting up your organization
-
-This happens once in the lifetime of an organization. These steps will be filled out as we develop this documentation further. Talk to us to learn more.
-
-1. [Create a docassemble server](https://suffolklitlab.org/legal-tech-class/docs/practical-guide-docassemble/setup-server)
-1. [Add the AssemblyLine package to your server](installation.md)
-1. [Copy](https://help.trello.com/article/802-copying-cards-lists-or-boards) the Trello [checklist boards](#trello-boards)
-
-You should also consider:
-
-1. [enabling GitHub Playground integration](https://docassemble.org/docs/config.html#github)
-2. inviting each developer who will use your server to [create their own accounts](https://docassemble.org/docs/users.html#add)


Is setting up an org covered somewhere else? Is it worth keeping?

This page was almost entirely geared towards replicating the Document Assembly Line concept of 2022, which as far as I can tell isn't how anyone is thinking about it any more (i.e., dozens or hundreds of people making small contributions regardless of their skill level).

The rest of it can be found elsewhere. For example, the GitHub documentation does a better job of documenting GitHub orgs, and the Docassemble documentation does a better job of documenting GitHub integrations and Docassemble server setup and configuration.

as far as I can tell isn't how anyone is thinking about it any more (i.e., dozens or hundreds of people making small contributions regardless of their skill level).

True, but I think a lot of our partners still use orgs. Orgs aren't just for hundreds of people. It doesn't need to be much. For example, it might be worth mentioning GitHub orgs with a link to the GitHub docs and maybe the docassemble docs.

plocket · 2024-08-30T17:26:24Z

docs/get_started/assembly_line_steps.md

-* [Building your first expert system](https://suffolklitlab.org/legal-tech-class/docs/interview-structure/building-an-app-outline)
-* Lauritsen and Soudakoff, [Keys to a Successful Document Assembly Project](https://static1.squarespace.com/static/571acb59e707ebff3074f461/t/5946f745725e25bf7ad93c9b/1497823045990/keys.pdf)


I haven't looked at these before. Are they worth keeping somewhere?

The first one is linked prominently on the Roadmap page. The second is super old. It might inform our documentation, but it's probably not worth including otherwise.

To play devil's advocate - the second link looks like it gets into a lot of details that we don't want to get into. It seems to be mostly about process, which I think doesn't age quite as quickly as a lot of tech articles do.

plocket · 2024-08-30T17:33:16Z

docs/get_started/assembly_line_steps_planning_time.md

-Excellent examples include:
-
-* [Illinois Legal Aid Online](https://www.illinoislegalaid.org/), [example landing page](https://www.illinoislegalaid.org/legal-information/divorce)
-* [Washington Law Help](https://www.washingtonlawhelp.org/), [example landing page](https://www.washingtonlawhelp.org/resource/parenting-plan-forms-online)


Good to have these examples?

Examples of live interviews now live on the intro page.

plocket · 2024-08-30T17:37:02Z

docs/get_started/working_with_teams.md

+title: Working with Teams
+sidebar_label: Working with Teams


This evokes Microsoft Teams for me. Also, I think the goal was to keep even titles of pages in sentence case, like our page titles in our interviews. Something about readability?

If there's a consensus on sentence case for titles and headings I'd like a chance to revisit it!

I think sentence case for titles and headings can make sense when titles and headings are longer, but in that case I think it's better to reconsider how you're using titles and headings. Docassemble questions are only headings in the HTML markup. To the user they function like a field label.

We are not consistent with title/sentence case inside the Docusaurus pages, but I do notice that most of the sections with more than one-word labels are in sentence case in our older pages, but title case on the new "getting started" section. We do recommend sentence case for headings inside the interview itself and I don't think we should revisit that rule.

I don't think this matters a lot, but we probably should be consistent. Maybe some of the section titles from the older content are naturally more "sentency"? E.g.:

I do think it's fair to say that sentence case is dominating on the web, and that when you look up recommendations overall about whether you should use sentence or title case, most of the newest recommendations say sentence case. If we have to be consistent, I'd suggest we adopt sentence case convention--it certainly won't look out of place, and it gives us one less thing for us to remember.

I believe Title Case was standardized in part when we had fewer options to vary emphasis, size, and weight of text in printed media.

plocket · 2024-09-01T12:05:55Z

docs/get_started/roadmap.md

+slug: /get_started/roadmap
+---
+
+Whether you are a LIT Clinic student, a recent [Forms Camp](https://www.ncsc.org/consulting-and-research/areas-of-expertise/access-to-justice/forms-camp) graduate, or anyone else getting started on an interview-building project—whether it is your first or fiftieth—this page will guide you through the stages of a successful project, from concept to launch.


Minor nit - This took me a couple re-reads to understand: "interview-building project—whether"

Good catch. This punctuation/sentence structure could be more clear.

plocket · 2024-09-03T01:37:29Z

docs/get_started/roadmap.md

+
+## Meeting Cadence
+
+Two recurring meetings will help you keep the project moving forward. These are short, 5–15 minute "standup" meetings to share progress and identify and remove blockers—anything preventing someone from making progress.


The meeting is 5-15 min long, or each person talks for 5-15 min? I don't remember having many group 5-15 min. meetings, but I did't attend the student meetings.

Yep, this matches the time we spend with 1-1 meetings between partners and builders. Our Monday calls are not being described here.

The standup portion of our meetings were definitely 5–15 minutes. As mentioned further down, we also included problem-solving time.

plocket · 2024-09-03T12:01:44Z

docs/get_started/assembly_line_steps_planning_time.md

-Spend some time **mapping out the process**. Decide where your app will intervene, and
-how you will help locate your users in the process. I.e., making sure they 


Is this stage of planning out of scope for us?

This page was super old and I deleted it, so …

This sounds like journey mapping. I'm not understanding whether this part of the process is out of scope. Even if you deleted the page, we still have access to its contents. I suspect just mentioning the motivation behind this and a link to more resources would probably be as much as our content can provide.

plocket · 2024-09-03T12:02:58Z

docs/get_started/assembly_line_steps_planning_time.md

-* Get familiar with the Docassemble playground and the structure of a YAML file by completing a [Hello, World](https://suffolklitlab.org/legal-tech-class/docs/classes/docacon-2020/hello-world) exercise. Use the [Docassemble Slack](https://docassemble.org/docs/support.html#tocAnchor-1-1) or our Teams channel when you get stuck.
-
-Give yourself 2-3 weeks to become familiar with Docassemble basics.


Is the hello world exercise useful somewhere? The link to docassemble slack (we have a link to the docs, but I don't think people find the Slack channel that way)? Are the time estimates in here useful? This one is just an example, but there are others.

plocket · 2024-09-03T12:05:19Z

docs/get_started/assembly_line_steps_planning_time.md

-
-## Refining and testing
-
-Almost all of your time will be in the refining and testing stage. You will take


This section has another couple places that do work setting expectations. The new guidelines can give the impression that the time is divided evenly between the different listed parts of the project. Maybe you found that they are, though. Or maybe setting these expectations is out of scope.

plocket · 2024-09-03T12:41:08Z

docs/get_started/assembly_line_steps_step_by_step.md

-Get feedback from your subject matter experts. Turn the feedback into actionable
-[Github](/docs/github) issues that you can triage later.
-
-### Getting plain language review


I'm sorry if I missed it - do the docs still bring up plain language as a consideration?

this is covered in the "Writing good questions" section

I can't find a link to the content we had before, which I think is now in the legal tech class content. Also, I don't remember (and didn't find) a plain language review being called out specifically.

samglover added 30 commits July 9, 2024 19:49

Create beginner's guide, workflow, and resources pages

073642c

Change sidebar label

0bebff4

Change sidebar label

3390198

Move planning and working with teams pages; update sidebar and links

eac8eb5

Draft beginner's guide

81d66ec

Rename workflow file

fb9237d

Start outline of the interview project workflow/roadmap page

6de28f9

Rename file

17ba389

Indentation

6d5b35a

Updates to draft interview project roadmap page

21de8fa

Merge branch 'main' into add_interview_builder_pages

eff0a60

Merge branch 'main' into add_interview_builder_pages

4277e56

Updates to the draft interview project roadmap page

d9ba750

Draft roadmap page updates

2fadd4e

Saving WIP

1ba595d

Saving WIP

deb6b38

Update interview_project_roadmap.md

04ace0e

Create advanced interview building page

04ab089

Update anchor

0451800

Saving WIP

3fcb6c0

Add URL watermark

3cb2985

Interview project roadmap first draft

a23a028

Delete and redirect the Roles page

6aed312

Delete and redirect Assembly Line steps/process page

024356a

Delete and redirect Step-by-step page

9787b4c

Move branding customization page

d255999

Move and rename theme customization page to ALThemeTemplate

b59e9d7

Delete advanced interview building page

eb4bfa6

Fix typo

e5c3397

samglover added 7 commits August 30, 2024 10:27

Delete and redirect the planning time and AL setup pages

37b3278

Revert "Delete advanced interview building page"

dcafb19

This reverts commit eb4bfa6.

Delete and redirect planning your interview page

a21eb0a

Add PDF v. DOCX considerations to the PDF and DOCX pages

3ac356d

Delete interview_building_tips.md

c7a0185

Rename roadmap file and rearrange sidebar

8424d19

Fix broken links

5e3c40c

samglover requested review from plocket and removed request for plocket August 30, 2024 17:00

samglover and others added 2 commits August 30, 2024 12:03

Merge branch 'main' into add_interview_builder_pages

1e61756

Fix broken links

5d44d14

samglover merged commit da485bc into main Aug 30, 2024
2 checks passed

samglover deleted the add_interview_builder_pages branch August 30, 2024 17:11

samglover mentioned this pull request Aug 30, 2024

Add clear labels for different audiences #165

Closed

plocket reviewed Sep 3, 2024

View reviewed changes

This was referenced Sep 3, 2024

Document resources/options/best practices for optimizing interviews for search engines #463

Closed

Update the interview project roadmap [checklist] #464

Closed

		* [Building your first expert system](https://suffolklitlab.org/legal-tech-class/docs/interview-structure/building-an-app-outline)
		* Lauritsen and Soudakoff, [Keys to a Successful Document Assembly Project](https://static1.squarespace.com/static/571acb59e707ebff3074f461/t/5946f745725e25bf7ad93c9b/1497823045990/keys.pdf)


		## Meeting Cadence

		Two recurring meetings will help you keep the project moving forward. These are short, 5–15 minute "standup" meetings to share progress and identify and remove blockers—anything preventing someone from making progress.

		Spend some time mapping out the process. Decide where your app will intervene, and
		how you will help locate your users in the process. I.e., making sure they

		* Get familiar with the Docassemble playground and the structure of a YAML file by completing a [Hello, World](https://suffolklitlab.org/legal-tech-class/docs/classes/docacon-2020/hello-world) exercise. Use the [Docassemble Slack](https://docassemble.org/docs/support.html#tocAnchor-1-1) or our Teams channel when you get stuck.

		Give yourself 2-3 weeks to become familiar with Docassemble basics.


		## Refining and testing

		Almost all of your time will be in the refining and testing stage. You will take

Add interview builder pages #459

Add interview builder pages #459

Uh oh!

Conversation

samglover commented Aug 30, 2024

Uh oh!

Uh oh!

plocket left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!