Interview project roadmap updates

docs/get_started/beginners_guide.md

@@ -1,7 +1,7 @@
 ---
 id: beginners_guide
-title: Learn to Build Docassemble Interviews
-sidebar_label: Beginner's Guide
+title: Learn to build Docassemble interviews
+sidebar_label: Beginner's guide
 slug: /get_started/beginners_guide
 ---
 
@@ -13,15 +13,15 @@ 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. [Review the interview project roadmap](#review-the-interview-project-roadmap)
+3. [Review the interview project management page](#review-the-interview-project-management-guide)
 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.
 :::
 
-## Do the Hello, World Exercise
+## Do the Hello, World exercise
 
 In his Legal Tech Class, Quinten Steenhuis introduces Docassemble with a [short "Hello, World" exercise](https://suffolklitlab.org/legal-tech-class/docs/classes/docacon-2020/hello-world). This introductory exercise is a great way to demystify Docassemble and see what it's like to build a simple interview—by actually doing it.
 
@@ -31,7 +31,7 @@ Once you have successfully completed the Hello, World exercise you might want to
 
 When you have finished the Hello, World exercise, move on to the next step: learning about the Weaver.
 
-## Watch a Demonstration of the Weaver
+## Watch a demonstration of the Weaver
 
 The Weaver is a Document Assembly Line tool that generates a draft Docassemble interview from a prepared PDF or DOCX form so you don't have to start from scratch. The best way to explain it is to see it in action:
 
@@ -43,25 +43,25 @@ 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
+## Review the interview project management guide
 
 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)**
+**➡️ [Review the interview project management guide.](project_management.md)**
 
-## Join the Document Assembly Line Community
+## 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.
 
 **➡️ [Email us to join the Document Assembly Line community.](mailto:litlab@suffolk.edu)**
 
 You can also take advantage of other [interview building resources and documentation](resources.md).
 
-## Start Building Your First Interview!
+## Start building your first interview!
 
-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!
+You probably already have an idea of the first form you want to work on, so pull up the [project management guide](project_management.md) and get started!
 
-## Learn More
+## Learn more
 
 If you've completed the above you are ready to get started building your first interview. But if you want a more in-depth beginner training, check out this 3.5–hour beginner training from [Docacon 2020](https://docacon.com/2020/index.html):
 

docs/get_started/intro.md

@@ -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/roadmap.md) for building [Docassemble](https://docassemble.org) interviews to assemble court forms for filing.
+* A [project management guide](/get_started/project_management.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.

docs/get_started/roadmap.md → docs/get_started/project_management.md

@@ -1,21 +1,21 @@
 ---
-id: roadmap
-title: Roadmap of a Successful Interview Project
-sidebar_label: Roadmap
-slug: /get_started/roadmap
+id: project_management
+title: Interview project management guide
+sidebar_label: Project management
+slug: /get_started/project_management
 ---
 
-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.
+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, this page will guide you through the stages of a successful project.
 
 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
+## Identify key roles & responsibilities
 
-![Interview Project Roles & Lines of Communication](../assets/interview-project-roles-communication.png)
+![Interview project roles & lines of communication](../assets/interview-project-roles-communication.png)
 
 Every interview project has:
 
@@ -27,7 +27,7 @@ Every interview project has:
 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
+### 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.
 
@@ -41,7 +41,7 @@ The decisionmaker's job is to gather and clarify stakeholders' feedback so that
 
 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
+## 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.
 
@@ -70,33 +70,34 @@ Here is a sample kickoff meeting agenda:
   * Decisionmaker/stakeholder feedback
   * Interview finalized and ready for go/no-go decision
   * Launch
+  * Promotion
 * 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:
+Consider [Henrik Kniberg's skateboard analogy](https://blog.crisp.se/2016/01/25/henrikkniberg/making-sense-of-mvp):
 
 ![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.
+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, stick to it. Don't add to the MVP without a compelling justification.
 :::
 
-## Complete the Draft Interview
+## 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
+## 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
+### 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.
 
@@ -114,7 +115,7 @@ The reason for sharing your progress and plan for the day or week is so that eve
 
 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
+### 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:
 
@@ -139,68 +140,60 @@ To get better answers, ask questions better. Here are some tips for asking quest
 
 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
+## 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
+### 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
+:::tip
+If you aren't sure where to find someone to give you preliminary feedback, try asking [the community](http://localhost:3000/docs/get_started#join-the-community)! Come to one of the Monday community meetings or ask in the Microsoft Teams forum.
+:::
 
-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.
+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
+### 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:
+Share the interview 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.)
+* At the top of each page of the interview is an ID. Use the ID to refer to specific interview pages, not a page number.
 
-## Revise the Interview
+## 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.
+Two rounds of feedback and revision are usually enough.
 :::
 
-## Get a Go/No-Go Decision
+## 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
+## Launch the interview
 
 When you are ready to launch, add the interview to your production server and make sure it works as intended.
 
@@ -212,20 +205,30 @@ Once the interview is live, consider how people who need it will find it.
 
 You can also set up [collect analytics](../analytics/tracking_usage) to learn how people are finding and using the interview.
 
-## Do a Retrospective
+## 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:
+If your interview project fails, a retrospective is an important tool for making sure you avoid another failure.
+
+To do a retrospective, the project manager should meet with each member of the group to discuss and document the answers to 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.
+Retrospectives are generally most effective one-on-one, in real 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.
+Use what you learn from the retrospective when planning your next interview-biulding project.
+
+## Tips from the community
+
+In a Document Assembly Line workshop, members of the community shared their tips for managing a successful interview-building project:
+
+<p align="center">
+  <iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/txm6VJVlG_Q" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
+</p>