diff --git a/docs/archive/bootcamp.md b/docs/archive/bootcamp.md index 2bca9d8c4..e57c147f1 100644 --- a/docs/archive/bootcamp.md +++ b/docs/archive/bootcamp.md @@ -6,7 +6,7 @@ slug: /archive/bootcamp --- :::info -This pages is about the bootcamp that we ran from February 18th, 2021 to March 11th, 2021. Although the camp is already finished, you can +This page is about the bootcamp that we ran from February 18th, 2021 to March 11th, 2021. Although the camp is already finished, you can follow along yourself using the resources on this page! ::: diff --git a/docs/assets/interview-project-roles-communication.png b/docs/assets/interview-project-roles-communication.png new file mode 100644 index 000000000..7279f9e15 Binary files /dev/null and b/docs/assets/interview-project-roles-communication.png differ diff --git a/docs/docx_templates.md b/docs/docx_templates.md index 75d0faf73..8298ba240 100644 --- a/docs/docx_templates.md +++ b/docs/docx_templates.md @@ -5,6 +5,22 @@ sidebar_label: Working with DOCX files slug: /docx --- +:::tip +Consider whether to use a PDF template instead. + +**Reasons to use DOCX:** + +* DOCX documents will grow or shrink to accomodate as much or as little information as the user provides +* DOCX documents allow you to use lists and repeated groups naturally and with little extra effort after labeling the first item +* DOCX documents allow you to easily make whole sections of a document contingent +* DOCX documents work well with linear content that is read by scanning down the page, not across + +**Reasons to avoid DOCX:** + +* DOCX documents do not work as well for content formatted in columns or that require precise layout +* DOCX document content may flow unexpectedly if it is longer than expected +::: + DOCX templates can be edited in any editor that is able to edit DOCX files, including: * Microsoft Word, or Microsoft Word Online diff --git a/docs/get_started/customization_overview.md b/docs/framework/althemetemplate.md similarity index 98% rename from docs/get_started/customization_overview.md rename to docs/framework/althemetemplate.md index 0394790a5..b3bac8dbd 100644 --- a/docs/get_started/customization_overview.md +++ b/docs/framework/althemetemplate.md @@ -1,8 +1,9 @@ --- -id: customization -title: Applying a custom theme or brand -sidebar_label: Applying a custom theme or brand -slug: /get_started/customization +id: althemetemplate +title: | + ALThemeTemplate: Applying a Custom Theme or Brand +sidebar_label: ALThemeTemplate +slug: /althemetemplate --- ## Sharing a custom look and feel across multiple Assembly Line interviews diff --git a/docs/get_started/assembly_line_setup.md b/docs/get_started/assembly_line_setup.md deleted file mode 100644 index 0e41863dd..000000000 --- a/docs/get_started/assembly_line_setup.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -id: assembly_line_setup -title: | - Set up your Document Assembly Line -sidebar_label: | - Set up your Document Assembly Line -slug: /get_started/assembly_line_setup ---- - - - -The guidance below is for organizations that want to set up their **own** copy of the Assembly Line, not for individual automators. - -How do you develop and deploy court forms effectively? This is what has worked -for us. Adjust it when you need to. We'd love to hear about the changes you make -for your organization! - -## 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) - -Below are some general techniques and knowledge we have found useful for starting the development of a form. - -## Developing a form - -The [Trello checklists](#trello-boards) are really the source of truth for developing a form. Much of the documentation on this site is meant mostly as reference material to support a developer as they work through the [step-by-step process](https://trello.com/c/uRD0ZIOc/1-form-name-type-of-law) this project has found useful. - -The broad strokes of the details you can see in the Trello checklists: - -1. Copy the template card in your organization's Trello board -1. [Move the card through the Trello lists/columns](#trello-boards), completing the checklists as you go -1. [Identify your MVP](#stick-to-an-mvp) -1. [Generate the code you will build off of](weaver_overview.md) -1. Edit the code of the interview -1. Get reviews on the interview -1. Submit the interview for approval, provisional on passing tests -1. Write tests for and test the interview -1. Deploy the interview - -## Stick to an MVP -**MVP:** Minimum viable product - first make something that works. - -Henrik Kniberg has [created a useful skateboard analogy for an MVP](https://blog.crisp.se/2016/01/25/henrikkniberg/making-sense-of-mvp). -![Minimum viable product](../assets/mvp.png) --- Henrik Kniberg - -An MVP will be different for different projects. The [legal form maturity model](https://suffolklitlab.org/legal-tech-class/docs/legal-tech-overview/maturity-model/#quick-summary) can help you identify your MVP. Once you've decided what this form's MVP is, avoid adding anything unless absolutely necessary. - -## Trello boards - -We have created three boards in Trello that help track the status of a form as it is being developed. Each of our forms has one card that is a copy of [the one template card](https://trello.com/c/uRD0ZIOc/1-form-name-type-of-law) and contains all the checklists. Those checklists walk a developer through the process step by step, providing resources along the way. They also keep track of what still needs to be done. - -You can [copy](https://help.trello.com/article/802-copying-cards-lists-or-boards) our Trello boards and adjust them to your needs: - -1. [AssemblyLine - Pre-processing Template Board](https://trello.com/b/Z2Svx3oh/1-assemblyline-pre-processing-template-board#) -1. [AssemblyLine - Development Template Board](https://trello.com/b/ArfGFbz4/2-assemblyline-development-template-board) -1. [AssemblyLine - Testing Template Board](https://trello.com/b/nT7yy2Wl/3-assemblyline-testing-template-board) - -Each column, or list, on a board is either associated with a checklist or is a [buffer list](#buffer-lists). A developer will create a card for their form and move it through the columns, or 'lists', of the trello board. If one developer has to leave the development of the form, another developer can pick up the card wherever it is on the boards. - -We recommend you keep all the checklists on that first card. Having developers add additional lists manually later turned out to be a logistical obstacle. - -Note: Trello is not required to implement this kind of system. It just happens to be the tool we used. - - - -### Buffer lists -You can see that every other column (list) is a 'buffer' list. Without buffer lists, it is hard to see what's going on with a project in the lists. Is the form done with this list and ready for the next one? Did it just arrive in this list? Is it being worked on actively by someone or does it need someone new to take hold of it? - -Buffer lists clarify this, though. If a card is not in a buffer list, the work of that list is not complete. When a card is in a buffer list, the previous list's tasks were finished and the form is waiting for someone to pick up the work. - -As a developer, you would: - -1. Pick a card in a buffer list -1. Move the card out of the buffer list into the list immediately to the right (a ‘work in progress’ list) -1. Add yourself as a member of the card if needed -1. Complete the appropriate checklist -1. If you have to leave the development of that form, remove yourself from the card -1. Move the card into the next buffer list. It will sit there till the next person picks it up. - -If a developer has to leave while in the middle of a task list, they can move the card to the previous buffer list to show that someone new needs to take over the work. diff --git a/docs/get_started/assembly_line_steps.md b/docs/get_started/assembly_line_steps.md deleted file mode 100644 index c1ff8fcb1..000000000 --- a/docs/get_started/assembly_line_steps.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -id: assembly_line_steps -title: The Assembly Line process -sidebar_label: The Assembly Line process -slug: /get_started/assembly_line_steps ---- - -:::warning -We are actively updating the Document Assembly Line workflow and much of the information in this section is outdated. -::: - -The guidance below is for organizations that want to set up their **own** copy of the -Assembly Line, not for individual automators. - -We think that the most important work we did came not from computer code, but a -process: the process of automating a legal form, broken down into a series of -small steps. - -## Our Trello boards {#trello} -We turned that process into a series of -[Kanban](https://blog.trello.com/kanban-data-nave) boards, and if you want you -can jump straight to -[copying](https://help.trello.com/article/802-copying-cards-lists-or-boards) and -customizing them for your needs: - -1. [AssemblyLine - Pre-processing Template Board](https://trello.com/b/Z2Svx3oh/1-assemblyline-pre-processing-template-board#) -1. [AssemblyLine - Development Template Board](https://trello.com/b/ArfGFbz4/2-assemblyline-development-template-board) -1. [AssemblyLine - Testing Template Board](https://trello.com/b/nT7yy2Wl/3-assemblyline-testing-template-board) - -## Overview - -Automating a form involves: - -* Research and vetting the substantive content -* Coding -* Adding labeled fields to a template document -* Generating and refining a prototype -* Testing and getting feedback - -## More reading - -* [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) \ No newline at end of file diff --git a/docs/get_started/assembly_line_steps_planning_time.md b/docs/get_started/assembly_line_steps_planning_time.md deleted file mode 100644 index fc3902918..000000000 --- a/docs/get_started/assembly_line_steps_planning_time.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -id: assembly_line_steps_planning_time -title: Planning your time -sidebar_label: Planning your time -slug: /get_started/assembly_line_steps/planning_time ---- - -:::warning -We are actively updating the Document Assembly Line workflow and much of the information in this section is outdated. -::: - -## Planning out your app - -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 -use your app at the right point in their journey and they have clearly communicated -next steps to complete the full journey. Rarely can a legal app complete the full -journey for a user. - -The time required for this phase varies depending on the scope you select for your app. -Plan to spend several hours at a minimum. Depending on how you involve stakeholders, -you may spend several weeks here. - -[Read more about planning](https://suffolklitlab.org/legal-tech-class/docs/interview-structure/building-an-app-outline/#the-planning-phase). - -## Gaining comfort with Docassemble - -If you are a completely new Docassemble developer, we recommend getting familiar in two steps: - -* 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. - -The Weaver is a guided process, but it may still take a few weeks to familiarize yourself with its options. Start with -a simple, already labeled form for your first experience. - -## Getting your first prototype - -To produce your first prototype, you must: - -1. [label your template](doc_vars_reference.md) and then -1. [automate it in the Weaver](weaver_overview.md). - -This first prototype will be very rough. It will not ask questions in the order that you want. -You may have extra questions or extra fields, or questions may be asked using our default -[question library](question_library/names.md) format and may need customization. - -Plan to spend about an hour in the Assembly Line Weaver. - -## Refining and testing - -Almost all of your time will be in the refining and testing stage. You will take -your draft output from the Weaver and start to [customize the -output](/docs/customizing_interview). You should then share your work in progress regularly -with subject matter experts to check your assumptions and to refine the content. - -You may spend several months here, even for a small project. You should be able to -get to a useful prototype stage within a few weeks, however, focusing on: - -1. asking just the questions you want, and customizing stock questions -1. getting the order of questions right -1. refining the input style choices, such as adding multiple-choice options -1. adding navigational elements - -Expect to have a lot of back and forth with your subject matter expert about -the language of your content. That is where most subject matter experts will -have experience and expertise. Be ready to push back where needed to address -our guidance on [asking good questions](question_style_overview.md). - -## Launching your product - -An app that nobody uses is not a good investment of your time. Plan your launch -strategy early, and budget at least a few weeks here. - -Our work has a built-in landing page: [courtformsonline.org](https://courtformsonline.org). - -Think about your landing page. A Docassemble interview is not indexable by Google, so you -should have a static site, perhaps in Wordpress or another technology you already use, to -highlight and direct someone to your app. - -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) - -Also consider building relationships with peers and organizations in control of -content. For an access to justice project (non-commercial) you will want to -build relationships directly with your regional legal help website, courts, -cities, and governmental partners to get direct links to your landing page on -their relevant self-help guides. - -Consider direct outreach to potential repeat users of your app. For a tool focused -on domestic violence, building an ongoing relationship with victims advocates in -the police department, legal aid, and domestic violence shelters, for example, will -lead to many more users of your app than any approach to reaching consumers directly. -Hopefully, most of your consumers will be one-time users. Advocates will use it -again and again. - -This direct outreach should be sustained over time. You can monitor analytics and -referrals to understand where your users are coming from and where to concentrate -your outreach. - -Consider if you have a budget and willingness to experiment with direct -acquisition of consumers via: - -* paid advertising -* creating and sharing a promo, bus ad, or other materials that may be free advertising sources -* posting flyers -* gaining earned media (it helps to have a partner like a city or university here!) - diff --git a/docs/get_started/assembly_line_steps_roles.md b/docs/get_started/assembly_line_steps_roles.md deleted file mode 100644 index 7dd7d5ce5..000000000 --- a/docs/get_started/assembly_line_steps_roles.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -id: assembly_line_steps_roles -title: Roles -sidebar_label: Roles -slug: /get_started/assembly_line_steps/roles ---- - -:::warning -We are actively updating the Document Assembly Line workflow and much of the information in this section is outdated. -::: - -It's common for one or more roles to be shared by a single person. On our project -we benefited from a lot of volunteers and the ability to split roles more evenly. Think -about finding people to play the following roles: - -* Project manager -* Researcher and content author -* Subject matter expert and liaison to subject matter expert -* Template cleanup and adding labeled fields (in Adobe Acrobat or Microsoft Word) -* Python coder -* Frontend / HTML / CSS / JavaScript coders -* Docassemble developer -* Plain language reviewer and editor -* Tester - -We found the most success in asking short-term volunteers to help with **testing**, -cleaning up and **adding labeled fields to templates**, and Python and frontend -**coding** (for discrete tasks that didn't demand too much familiarity with our -whole code base). **Subject matter experts**, similarly, did not require a long-term -commitment to the project, but did require some orientation to understand what -an interactive legal application can and should do. - -Longer-term members of our team fit more naturally into other roles. People often -changed roles and overlapped them over the time that they volunteered. For example: -almost all of our members did some Docassemble development as they gained comfort -and familiarity as the project went on. - -Project management is a learned skill that fit well with people who were -outgoing and organized, and also did not demand extensive coding experience. We -found it necessary to have a project manager role to make sure content actually -got out the door. Otherwise, apps could spend too much time in the refining -stage. The urgency of the pandemic helped us center delivering working apps as a -goal. - -While not an explicit role in the project, we also found it important to share -our work in progress with community groups and stakeholder groups early to gain -important insights about features and how our project should be designed. Often, -this was in the form of a demo with an explicit ask for feedback, so at the stage -a bit beyond the useful prototype stage. \ No newline at end of file diff --git a/docs/get_started/assembly_line_steps_step_by_step.md b/docs/get_started/assembly_line_steps_step_by_step.md deleted file mode 100644 index d01d3c6fa..000000000 --- a/docs/get_started/assembly_line_steps_step_by_step.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -id: assembly_line_steps_step_by_step -title: Step-by-step -sidebar_label: Step-by-step -slug: /get_started/assembly_line_steps/steps ---- - -:::warning -We are actively updating the Document Assembly Line workflow and much of the information in this section is outdated. -::: - -The guidance below is for organizations that want to set up their **own** copy of the Assembly Line, not for individual automators. - -Below is a brief explanation of the content on our sample Trello boards. - -## Pre-processing - -The [pre-processing Trello board](https://trello.com/b/Z2Svx3oh/1-assemblyline-pre-processing-template-board#) is -where you will: - -1. clean up the template file -1. add our standardized labels -1. get a peer to review your work adding labels to catch mistakes early on - -## Development - -The phase that you will spend the most time on for your app--development--gets -just one Trello board. - -[Development Template Board](https://trello.com/b/ArfGFbz4/2-assemblyline-development-template-board) - -### Using the Weaver - -First, run your form through the [Weaver](weaver_overview.md). - -### Refining in the Docassemble playground - -Next, [customize your form](customizing_interview.md). - -### Getting expert review - -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 - -Hopefully you kept in mind our guidance on [writing good -questions](/docs/style_guide/question_overview). Nevertheless, get a second opinion that -focuses just on how readable and easy to understand the substantive content -of your app is. - -### Getting feedback from team members and external stakeholders - -At our peak, we had multiple weekly meetings with 5-15 members of our team. -These were excellent places to ask developers to demonstrate their work and get more -holistic feedback on the app: focusing on aspects including: - -* [appropriate use of fields](question_style_organize_fields.md) -* [interview structure](question_style_structure.md) - -and any other aspects that required a bigger-picture view of the app. - -On a smaller team, you may want to set up structured demos with potential -stakeholders. - -If you have time, budget, and access to real users, you may set up one-on-one -or focus-group sessions to observe real users of your product. - -Assembly line forms also include an embedded feedback link that will create a GitHub -issue, so if you lack the ability to set up structured sessions, you could -directly share a testing link with potential users to get feedback. - -In either case: use this time, again, to turn the feedback into [actionable -Github issues](/docs/github). Spend time afterwards triaging and prioritizing the -feedback. - -### Iteration - -The point of gathering this feedback, of course, is to move on from your first -runnable prototype into a refined final product. - -[Read more about iteration](https://suffolklitlab.org/legal-tech-class/docs/interview-structure/building-an-app-outline/#iteration-and-testing). - -Some important points to keep in mind is: - -1. not all feedback can be implemented -1. an imperfect tool may be better than a perfect tool that is never released or used. - -We developed the [legal app maturity -model](https://suffolklitlab.org/legal-tech-class/docs/legal-tech-overview/maturity-model) -to provide a very concrete guidance as to which features should be prioritized. - -## Testing - -Testing should be incorporated into multiple stages of development, but we -provided some more specific guidance on our [testing Trello board](https://trello.com/b/nT7yy2Wl/3-assemblyline-testing-template-board). - -We found it effective to [test using this approach](https://suffolklitlab.org/legal-tech-class/docs/testing/testing-scenarios): - -1. understand and create a high-level feature matrix -1. write realistic user scenarios that provide good coverage of the features you - want to test -1. use multiple testers to use the scenarios as a rough guide to help with - quasi-random input testing. - -It is a good idea to ask your testers to record their tests on Zoom as they -work. This lets you rewind and spot the exact sequence of events that causes an -error. diff --git a/docs/get_started/beginners_guide.md b/docs/get_started/beginners_guide.md index 9db2d8eab..7733e5014 100644 --- a/docs/get_started/beginners_guide.md +++ b/docs/get_started/beginners_guide.md @@ -13,8 +13,9 @@ Here are the steps: 1. [Do the Hello, World exercise](#do-the-hello-world-exercise) for a friendly introduction to Docassemble 2. [Watch a demonstration of the Weaver](#watch-a-demonstration-of-the-weaver), a Document Assembly Line tool for quickly turning prepared forms into draft Docassemble interviews -3. [Join the Document Assembly Line community](#join-the-document-assembly-line-community) -4. [Start building your first interview!](#start-building-your-first-interview) +3. [Review the interview project roadmap](#review-the-interview-project-roadmap) +4. [Join the Document Assembly Line community](#join-the-document-assembly-line-community) +5. [Start building your first interview!](#start-building-your-first-interview) :::tip In order to build interviews you will need access to a [Docassemble playground](https://docassemble.org/docs/playground.html). But if you don't have one you can use ours! Register an account on the [LIT Lab Docassemble development server](https://apps-dev.suffolklitlab.org/user/register), then [email us](mailto:litlab@suffolk.edu) and ask for developer privileges. @@ -42,6 +43,12 @@ The interview generated by the Weaver is not a finished interview. It is a start Now you are probably itching to start building your first interview! But before you do, take a moment to review the interview-building workflow and join the Document Assembly Line community. +## Review the Interview Project Roadmap + +Building a successful interview involves more than just coding in the Docassemble playground. You'll also need to consider things like project management, [working with a team](working_with_teams.md), [requirements](working_with_teams.md#understanding-the-projects-users-and-intended-purpose), [usability](../question_style_overview.md), [testing](/alkiln/intro.mdx), etc. + +**➡️ [Review the interview-building workflow.](roadmap.md)** + ## Join the Document Assembly Line Community You know enough to get started, but you will need help. The Document Assembly Line community meets weekly on Zoom for live support, and coding help is available 24/7 in our Microsoft Teams forum. @@ -52,7 +59,7 @@ You can also take advantage of other [interview building resources and documenta ## Start Building Your First Interview! -You probably already have an idea of the first form you want to work on, so get started! +You probably already have an idea of the first form you want to work on, so pull up the [workflow](roadmap.md) and get started! ## Learn More diff --git a/docs/get_started/installation.md b/docs/get_started/installation.md index eddfa0de7..799f2659a 100644 --- a/docs/get_started/installation.md +++ b/docs/get_started/installation.md @@ -1,7 +1,7 @@ --- id: installation title: Installing the Document Assembly Line -sidebar_label: Installation +sidebar_label: Install the Assembly Line slug: /get_started/installation --- @@ -80,7 +80,7 @@ them for your own jurisdiction or organization. To use this package, [pull it into your own Docassemble playground](https://docassemble.org/docs/playground.html#packages). -Next, [follow our guide](customization_overview.md) to edit the YAML files and add a custom CSS theme to fit your own organization's needs. +Next, [follow our guide](/framework/althemetemplate.md) to edit the YAML files and add a custom CSS theme to fit your own organization's needs. Now, create a new package from the [Playground packages menu](https://docassemble.org/docs/playground.html#packages). Give the package a meaningful name, like LouisianaSharedBranding. diff --git a/docs/get_started/intro.md b/docs/get_started/intro.md index de9b3f399..6e39b5618 100644 --- a/docs/get_started/intro.md +++ b/docs/get_started/intro.md @@ -1,7 +1,7 @@ --- id: intro title: Introduction to the Document Assembly Line -sidebar_label: Intro +sidebar_label: Introduction slug: /get_started --- @@ -17,7 +17,7 @@ This short, 3-minute video by David Colarusso and Quinten Steenhuis explains how The LIT Lab gathered more than 200 volunteers from around the world and built tools such as: -* An [workflow](get_started/assembly_line_steps) for building [Docassemble](https://docassemble.org) interviews to assemble court forms for filing. +* An [workflow](/get_started/roadmap.md) for building [Docassemble](https://docassemble.org) interviews to assemble court forms for filing. * The core [Document Assembly Line Tools](https://github.com/SuffolkLITLab/docassemble-AssemblyLine), to make it easier to use key Docassemble features. * The [the Weaver](generating_code), a tool for converting existing PDF and DOCX court forms into draft Docassemble interviews in as little as one hour. * A [library](question_library/names) of pre-built, commonly used, accessible questions, vetted by experts and translated into at least 5 languages. diff --git a/docs/get_started/roadmap.md b/docs/get_started/roadmap.md new file mode 100644 index 000000000..f6e4714b9 --- /dev/null +++ b/docs/get_started/roadmap.md @@ -0,0 +1,231 @@ +--- +id: roadmap +title: Roadmap of a Successful Interview Project +sidebar_label: Roadmap +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. + +This roadmap reflects the procedures, templates, and tools the LIT Lab uses on our own interview-building projects, which you can adapt to your projects. + +:::tip +If this is your first interview-building project, it may help to read more about [planning and building your first expert system](https://projects.suffolklitlab.org/legal-tech-class/docs/interview-structure/building-an-app-outline). +::: + +## Identify Key Roles & Responsibilities + +![Interview Project Roles & Lines of Communication](../assets/interview-project-roles-communication.png) + +Every interview project has: + +1. **Interview builders.** The person or team responsible for building the actual interview. +2. **Decisionmaker.** One person who is responsible for managing stakeholders and converting their feedback into clear decisions for the interview builders. +3. **Stakeholders.** Anyone who needs to have a say in the interview project, such as managers, judges, clerks, subject matter experts, IT staff, and users (self-represented litigants and lawyers). + +:::note +You may have a team of interview builders and dozens of stakeholders, or you may be the only person working on this project. Even if this is a solo project, it helps to keep your different roles in mind. +::: + +### The Decisionmaker + +**While a successful interview project needs all these roles, the decisionmaker is especially important.** Most interview projects involve multiple stakeholders. When the interview building team requests guidance or feedback, multiple stakeholders may give multiple responses that may be confusing or conflicting and dramatically slow progress. + +The decisionmaker's job is to gather and clarify stakeholders' feedback so that interview builders have clear decisions to work from. The decisionmaker's responsibilities also include: + +* Being a single point of contact and single source of decisions +* Regular meetings with the interview building team +* Timely responses to requests for decisions and feedback +* Gathering feedback or approvals from stakeholders and converting it to clear decisions +* Making the go/no-go decision to launch the interview + +The decisionmaker must either (1) have the authority necessary to carry out these responsiblities, or (2) be responsible for getting authority when necessary. + +## Kickoff Meeting + +Schedule a kickoff meeting for the project as early as possible. The interview building team, the decisionmaker, and the key stakeholders should attend. + +The goal of a kickoff meeting is to get everyone on the same page when it comes to roles, expectations, and timeline. A good kickoff meeting sets the stage for a successful project. + +Here is a sample kickoff meeting agenda: + +* Introductions +* Identify the decisionmaker +* Development process overview (use this page) +* Schedule regular check-ins with the decisionmaker and one or two key stakeholders +* Introduce the source form/document, its context, and its users. In other words: + * Who can use this interview? In which language(s) will they be able to read and write? (Consider creating a couple of [user personas](https://en.wikipedia.org/wiki/Persona_(user_experience)) together.) + * What are they called (i.e., plaintiff, respondent, or appellee)? + * What can/can't this interview be used to do? + * Explain the court process leading up to someone using this interview. + * Identify the substantive laws or procedural rules the interview builders should be familiar with. + * Where and how must the completed documents be filed, served, or delivered? +* Agree on a [minimum viable product (MVP)](#stick-to-an-mvp) +* Define the requirements for this interview +* Agree on a process for changing the scope of the project (i.e., adding features) +* Discuss the timeline. Key dates: + * Start date + * Draft interview completed + * Preliminary feedback + * Decisionmaker/stakeholder feedback + * Interview finalized and ready for go/no-go decision + * Launch +* Discuss what success looks like for this project, and how you will measure it +* Consider doing a [pre-mortem](https://en.wikipedia.org/wiki/Pre-mortem)—imagine this project has failed and discuss why + +:::tip +### Stick to an MVP +A minimum viable product (MVP) is the essence of of iterative, incremental development—first make something that works, then make it better. + +Consider Henrik Kniberg's skateboard analogy: + +![Minimum viable product](../assets/mvp.png) + +Different projects will have different MVPs/"skateboards". The [legal form maturity model](https://suffolklitlab.org/legal-tech-class/docs/legal-tech-overview/maturity-model/#quick-summary) can help you identify the MVP for your project (interviews built for the general public should usually target level 2+). Once you decide what this project's MVP is, avoid adding anything more to it. +::: + +## Complete the Draft Interview + +After the kickoff meeting it is time to get to work! As you work on the interview, follow the [GitHub workflow](../github.md#workflow). If you get stuck on a problem for more than twenty minutes, ask for help. (Use the [Resources](resources.md) page to find options.) + +:::tip +The LIT Lab's [interview project template](https://github.com/orgs/SuffolkLITLab/projects/22) can help you keep your project organized and on track. Just click the **Use this template** button to use it. (You'll need a free [GitHub](../github.md) account.) +::: + +## 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. + +### Interview-Building Team Meetings + +The interview-building team should meet frequently. Daily check-ins are common on active projects, and anything less than weekly is unlikely to be effective. + +:::tip +Consider incorporating our Monday community meetings into your standup schedule. We run them standup-style, with time for solving blockers as a group. If this is a solo project, the Document Assembly Line community can be part of your interview-building team! +::: + +These meetings should follow a straightforward standing agenda. Each person on the team should share: + +1. **Progress:** what they worked on or accomplished since the last meeting +2. **Plan:** what they are working on now +3. **Blockers:** issues that are preventing them from making progress + +The reason for sharing your progress and plan for the day or week is so that everyone has an idea what everyone else is working on. This is necessary for the project manager, and can help interview builders avoid code conflicts or identify when it's time to merge branches. + +The reason for sharing blockers is to get help. Some teams reserve a larger block of time and use it to solve blockers together, like we do in our Monday community meetings. Other teams prefer to solve blockers separately. And sometimes a blocker is a question you need answered by the decisionmaker. + +### Decisionmaker Meetings + +Weekly or every-other week meetings with the decisionmaker and one or two key stakeholders are a chance to keep them informed of your progress and get decisions when you need them to move forward. The standing agenda is similar to the one above: + +1. **Progress:** what the interview-building team worked on or accomplished since the last meeting +2. **Plan:** what the interview-building team plans to work on between now and the next meeting +3. **Questions:** oustanding questions that are preventing the interview-building team from making progress + +When sharing progress and the current plan, it can help to give a percentage estimate. Something like: "We think we are about 30% of the way to a complete draft interview, and by our next meeting we hope to be at 50%." + +:::tip +Use [GitHub issues](../github.md#use-issues) to keep track of your questions for the decisionmaker. If you add a **question** label to issues, it is easy to pull up the list of your questions during a meeting. +::: + +To get better answers, ask questions better. Here are some tips for asking questions: + +* Only ask for a decisions when you can't make it yourself. Before you pose a question to the decisionmaker, ask your interview-building team (or the community). +* Avoid open-ended questions. When you decide to pose a question to the decisionmaker, give them two or three options and explain the pros, cons, and implications of each. +* If you do ask an open-ended question, explain that you are trying to generate ideas, not decide on a solution. +* Don't ask the decisionmaker to design the interview. It is usually better to ask for goals ("Do you need the attorney's ID number?"), not details ("Do you want the ID number field to show up right under the attorney's name field?"). + +**Remember: if you ask a question you will get an answer.** If you don't need an answer, asking for one is not likely to help and may complicate the project. + +Finally, when showing the relevant part of the interview as part of asking a question, remind the decisionmaker and stakeholders that the interview is a work in progress and you are not ready for feedback beyond the answer to your question. + +## Get Feedback on the Interview + +Once the interview works from start to finish and you have closed all the issues that are in scope for the [MVP](#stick-to-an-mvp), it is ready for feedback. Start by getting preliminary feedback from someone with Document Assembly Line experience. After you have made revisions based on the preliminary feedback, give the interview to the decisionmaker and stakeholders for their feedback. + +:::tip +For complex interviews that involve multiple forms/templates, consider doing this in stages. Start with the simplest form and get preliminary and stakeholder feedback early. Then move on to the most complex form to confirm the shape and logic of the overall interview. Then continue with the remaining forms. +::: + +### Preliminary Feedback + +Before you show the interview to the decisionmaker and stakeholders, get someone with Document Assembly Line experience to test it with you. This will help you identify issues you may have missed and questions you still need to ask the decisionmaker. + +To get the interview ready: + +1. [Merge your code](../github#create-a-pull-request) into **main** or a testing branch +2. [Create a new playground project](../github#create-and-manage-playground-projects) for the interview demonstration and pull your code into it +3. Make sure the interview works as expected in the testing project + +Once the interview is ready, schedule a video meeting with the tester so you can watch them go through the interview. Or they can watch you demonstrate it. Record the test if you can so you can focus on the test instead of taking notes. + +During the demonstration or testing: + +* Encourage the tester to comment on all aspects of the interview +* Ask them to follow different branches of the interview logic +* Listen carefully to their feedback and ask follow-up questions to make sure you understand it + +### Stakeholder Feedback + +Once you have closed all the issues that are in scope for the [MVP](#stick-to-an-mvp) and tested the interview yourself, it should be ready to hand off to the decisionmaker and stakeholders for their testing and feedback. + +Get the interview ready the same as [above](#preliminary-feedback), then click the **Share** button in the testing project playground to get the link to the interview. + +:::tip +When sharing the interview link, make sure the URL ends with `#page1`. If you have been testing the interview the **Share** link will point to the last page you were viewing instead of the start of the interview. Usually this won't matter, but it could result in unexpected behavior. +::: + +Share the link with the decisionmaker and give them a few tips for giving helpful feedback: + +* The feedback should come in the form of a written list of requested changes +* If there is confusing or conflicting feedback from stakeholders it is the decisionmaker's responsiblity to clarify it before presenting it to the interview building team +* Change requests should be specific. For example, if the text of a question should be changed, the change request should include the new text. +* At the top of each page of the interview is an ID. This ID is a reliable identifier when referring to an interview page. (For example, the "fifth page" might be different depending on the interview logic.) + +## Revise the Interview + +After getting feedback, create a [GitHub issue](../github#use-issues) for each change request from the tester or decisionmaker. Consider this your "punch list" to finish the project. Then get back to work on those issues! + +When you have closed all the issues/items on your punch list, send it back to the decisionmaker for further feedback. Each round of feedback should result in fewer change requests and move the project closer to completion. + +:::info +Two rounds of feedback and revision are usually enough. It it takes more than three, consider ways to improve your process going forward. +::: + +## Get a Go/No-Go Decision + +When the interview is complete, there is one last decision for the decisionmaker to make: whether the interview is ready to go live. + +If the answer is yes, launch the interview! + +If the answer is no, find out if further revision would result in a yes. If not, [do a retrospective](#do-a-retrospective) and try to understand what happened. + +## Launch the Interview + +When you are ready to launch, add the interview to your production server and make sure it works as intended. + +Once the interview is live, consider how people who need it will find it. + +* You should have a dedicated page on your website that tells people about the interview and links to it. Put some thought into this page so people can find it by searching Google. +* Others might want to direct people to the interview, like courts, legal aid organizations, and other advocates. Ask them to link to your landing page from their own websites. +* Paid advertising can help spread awareness, if you have a budget for it. + +You can also set up [collect analytics](../analytics/tracking_usage) to learn how people are finding and using the interview. + +## Do a Retrospective + +Before you start another interview-building project, pause briefly for a retrospective on how this one went. The retrospective format comes from [Agile software development](https://en.wikipedia.org/wiki/Agile_software_development), and it is a way to embrace continuous improvement by taking a moment to reflect on the project you just finished in order to improve the next one. + +To do a retrospective, gather the group and discuss three questions: + +1. What went well that we should keep doing? +2. What did not go well that we should stop doing? +3. What should we try going forward? + +Retrospectives are generally more effective when the team is together in real time—on Zoom, for example. Depending on the group dynamics you can do a retrospective as a group or meet with one person at a time. + +:::tip +Insist that everyone give at least one answer to each question. Even if someone insists nothing went badly, ask if they found themselves confused or struggling at any point during the project. Their answer may lead to an area that could be improved. +::: + +Use what you learn from the retrospective when planning your next interview-biulding project. \ No newline at end of file diff --git a/docs/get_started/working_with_teams.md b/docs/get_started/working_with_teams.md index 29e075eea..3de4daa3a 100644 --- a/docs/get_started/working_with_teams.md +++ b/docs/get_started/working_with_teams.md @@ -1,10 +1,14 @@ --- id: working_with_teams -title: Working with teams -sidebar_label: Working with teams +title: Working with Teams +sidebar_label: Working with Teams slug: /get_started/working_with_teams --- +:::warning +We are actively updating the Document Assembly Line documentation and much of the information on this page is outdated. +::: + ## Getting the project started ### Identify decision makers, team members, and sources of information diff --git a/docs/pdf_templates.md b/docs/pdf_templates.md index dd0f97563..d74d426b2 100644 --- a/docs/pdf_templates.md +++ b/docs/pdf_templates.md @@ -5,6 +5,21 @@ sidebar_label: Working with PDF files slug: /pdfs --- +:::tip +Consider whether to use a DOCX template instead. + +**Reasons to use PDF:** + +* PDF files may be the best choice if you are automating an approved court form that already exists as a PDF +* PDF files are good for heavily formatted content that includes columns and multiple fields on a single line + +**Reasons to avoid PDF:** + +* PDF documents are rigid, and may not contain enough room for real-world information +* Conditional logic must be applied field-by-field +* Lists and repeated data must be labeled one field at a time +::: + ## Edit your PDF PDF templates can be edited in: @@ -13,9 +28,7 @@ PDF templates can be edited in: * [the Documate online free PDF editor](https://www.documate.org/pdf) * many other PDF editors that support Acrobat Forms (mostly paid) -The free [Documate PDF -editor](https://www.documate.org/pdf) will meet most people's needs. It will allow -you to: +The free [Documate PDF editor](https://www.documate.org/pdf) will meet most people's needs. It will allow you to: 1. add text, checkbox, and digital signature fields 1. easily rename fields @@ -25,9 +38,7 @@ Documate has [a page that talks about its PDF editor](https://help.documate.org/articles/unlocking-pdf-documents). Adobe Acrobat can still be helpful. The most important feature it has that -Documate lacks is the ability to automatically recognize blank spaces and turn -them into fields. You may decide to use a trial version of Adobe Acrobat for -this feature, which is only needed at the beginning of your project. +Documate lacks is the ability to automatically recognize blank spaces and turn them into fields. You may decide to use a trial version of Adobe Acrobat for this feature, which is only needed at the beginning of your project. Watch a 2 minute video segment on [how to edit a PDF](https://help.documate.org/articles/unlocking-pdf-documents) with Documate's editor. diff --git a/docs/weaver_overview.md b/docs/weaver_overview.md index 54e738dbe..220941d93 100644 --- a/docs/weaver_overview.md +++ b/docs/weaver_overview.md @@ -53,7 +53,7 @@ to continue editing your code. The steps that the Weaver will walk you through are as follows: 1. validate the labels and your template file -1. add some basic information about your form (follow the [planning your interview](/get_started/plan_interview.md) to get this ready) +1. add some basic information about your form 1. add on-screen prompts for each labeled field 1. choose a datatype for each labeled field (for example: text, number, date) 1. organize the fields onto individual screens with headings and optional additional text diff --git a/docusaurus.config.js b/docusaurus.config.js index 206461d2b..ad38ff5f2 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -100,33 +100,33 @@ module.exports = { from: '/docs/installation', to: '/docs/get_started/installation' }, - { - from: '/docs/getting_started', - to: '/docs/get_started/assembly_line_setup' - }, { from: '/docs/assembly_line_steps', - to: '/docs/get_started/assembly_line_steps' + to: '/docs/get_started/roadmap' }, { from: '/docs/assembly_line_steps/roles', - to: '/docs/get_started/assembly_line_steps/roles' + to: '/docs/get_started/roadmap#identify-key-roles--responsibilities' }, { - from: '/docs/assembly_line_steps/planning_time', - to: '/docs/get_started/assembly_line_steps/planning_time' + from: '/docs/assembly_line_steps/steps', + to: '/docs/get_started/roadmap' }, { - from: '/docs/assembly_line_steps/steps', - to: '/docs/get_started/assembly_line_steps/steps' + from: '/docs/bootcamp', + to: '/docs/archive/bootcamp' }, { - from: '/docs/customization', - to: '/docs/get_started/customization' + from: '/docs/get_started/assembly_line_steps/roles', + to: '/docs/get_started/roadmap#identify-key-roles--responsibilities' }, { - from: '/docs/bootcamp', - to: '/docs/archive/bootcamp' + from: '/docs/get_started/assembly_line_steps', + to: '/docs/get_started/roadmap' + }, + { + from: '/docs/get_started/assembly_line_steps/steps', + to: '/docs/get_started/roadmap' }, { from: '/docs/planning', diff --git a/sidebars.js b/sidebars.js index c3db7db88..400fd9d5b 100644 --- a/sidebars.js +++ b/sidebars.js @@ -6,21 +6,16 @@ module.exports = { 'get_started/al_project_architecture', 'get_started/installation', 'get_started/beginners_guide', - 'get_started/plan_interview', - 'get_started/working_with_teams', - 'get_started/resources', { type: 'category', - label: 'Setting up your team', + label: 'Interview Projects', items: [ - 'get_started/assembly_line_setup', - 'get_started/assembly_line_steps', - 'get_started/assembly_line_steps_roles', - 'get_started/assembly_line_steps_planning_time', - 'get_started/assembly_line_steps_step_by_step', - 'get_started/customization', + 'get_started/roadmap', + 'get_started/working_with_teams', ], + collapsed: false, }, + 'get_started/resources', 'contributors', { type: 'category', @@ -140,6 +135,7 @@ module.exports = { ] }, 'framework/alrecipes', + 'framework/althemetemplate', 'complexity/complexity', 'framework/github_feedback', 'analytics/tracking_usage',