diff --git a/docs/phase-2-30-day-plan.md b/docs/phase-2-30-day-plan.md new file mode 100644 index 0000000..e2d17ab --- /dev/null +++ b/docs/phase-2-30-day-plan.md @@ -0,0 +1,102 @@ +# Phase 2 30-Day Organic Outreach Plan + +This plan assumes zero traction, no paid budget, and no automation. + +## Before Day 1 + +- Create recommended GitHub labels. +- Enable GitHub Discussions if ready to respond. +- Configure discussion categories. +- Create at least 5 starter issues from [phase-2-starter-issues.md](phase-2-starter-issues.md). +- Prepare a private tracker using [phase-2-outreach-tracker.md](phase-2-outreach-tracker.md). +- Confirm public demo credentials and warning language are current. + +## Week 1: Setup and Warm Review + +Goals: +- Publish first starter issues. +- Publish welcome discussion if Discussions is enabled. +- Ask 3 to 5 trusted people for bounded review. + +Actions: +- Create starter issues manually. +- Post the welcome discussion. +- Send 1 or 2 educator review requests. +- Send 1 or 2 developer onboarding review requests. +- Track responses privately. + +## Week 2: First Direct Outreach + +Goals: +- Begin targeted outreach to specific communities. +- Avoid mass posting. + +Actions: +- Contact 2 educators or educator groups. +- Contact 2 developer/open-source people or groups. +- Contact 1 HBCU department, student group, or faculty contact. +- Ask for one bounded action: review one flow, test setup, or suggest one better contact. +- Convert any concrete feedback into issues. + +## Week 3: First Sessions and Issue Conversion + +Goals: +- Run or schedule one small demo walkthrough or asynchronous office-hours thread. +- Convert feedback into visible work. + +Actions: +- Hold one 30-minute demo walkthrough or create an asynchronous GitHub Discussions office-hours thread. +- Invite 2 to 3 reviewers, not a broad audience. +- Create issues for repeated feedback. +- Update starter issue list if some issues are too vague. + +## Week 4: Review, Refine, and Decide Next Step + +Goals: +- Measure what happened. +- Decide whether to continue, narrow, or pause outreach. + +Actions: +- Review outreach tracker. +- Count replies, feedback quality, issues created, and contributor interest. +- Thank participants who opted into follow-up. +- Update README/docs if repeated confusion appears. +- Decide whether to expand outreach or run a second small cohort. + +## Minimum Daily Routine + +On outreach days, keep it small: + +1. Review tracker for next follow-up. +2. Send up to 2 thoughtful messages. +3. Respond to any replies. +4. Convert one actionable feedback item into an issue or note. +5. Stop before outreach becomes spammy. + +## First 10 Target Audience Types + +1. Black K-5 educators. +2. African-American studies educators. +3. Black homeschool group organizers. +4. HBCU education faculty. +5. HBCU computer science faculty. +6. HBCU NSBE or student developer groups. +7. Black software developer communities. +8. Open-source contributors focused on education, civic tech, or accessibility. +9. Africa-focused education technology contacts. +10. Caribbean studies, diaspora studies, or community learning organizers. + +## Zero-Traction Success Metrics + +Track practical early indicators: + +- 10 to 20 thoughtful outreach messages sent. +- 3 to 5 replies. +- 2 to 3 demo reviews. +- 1 educator review session or asynchronous thread. +- 1 developer setup review. +- 5 starter issues created. +- 3 actionable issues created from feedback. +- 1 potential contributor or reviewer willing to stay in touch. + +Do not treat stars, likes, or impressions as the main success metric in the first 30 days. diff --git a/docs/phase-2-community-launch-workflow.md b/docs/phase-2-community-launch-workflow.md new file mode 100644 index 0000000..e1df10c --- /dev/null +++ b/docs/phase-2-community-launch-workflow.md @@ -0,0 +1,108 @@ +# Phase 2 Community Launch Workflow + +This workflow opens the first community surfaces manually and carefully. It does not contact anyone by itself. + +## Manual GitHub Discussions Setup + +Repository owner steps: + +1. Open the GitHub repository. +2. Go to `Settings`. +3. Scroll to `Features`. +4. Enable `Discussions`. +5. Create or confirm these categories: + - Announcements + - Introductions + - Q&A + - Educator feedback + - Contributor help + - Roadmap + - Show and tell + +Before posting: +- Create labels from [github-community-setup.md](github-community-setup.md). +- Create starter issues from [phase-2-starter-issues.md](phase-2-starter-issues.md). +- Confirm the public demo guide is current. + +## First Welcome Discussion + +Use the welcome post from [phase-2-outreach-assets.md](phase-2-outreach-assets.md). + +Suggested category: `Announcements` or `Introductions` + +Pin it if GitHub allows. + +## First Demo Walkthrough Plan + +Audience: +- educators +- developers +- community organizers +- trusted reviewers + +Length: 30 minutes + +Prep: +- Confirm demo login works. +- Keep [public-demo.md](public-demo.md) open. +- Have starter issues ready. +- Prepare a note that the demo is shared and not for real learner data. + +Agenda: + +1. 3 minutes: mission and current stage. +2. 5 minutes: public landing page and README. +3. 10 minutes: student demo flow as `normalstudent`. +4. 5 minutes: teacher or admin surface if audience needs it. +5. 5 minutes: contribution and feedback paths. +6. 2 minutes: ask for one bounded follow-up action. + +Follow-up: +- Share the feedback issue template. +- Convert concrete feedback into GitHub issues. +- Ask whether reviewers want recognition before public credit. + +## First Office Hours Plan + +Format options: +- GitHub Discussions thread for asynchronous office hours. +- 30-minute video call if there is enough interest. +- One-on-one setup help for a first contributor. + +Boundaries: +- Keep it to one topic: setup, demo review, or starter issues. +- Do not promise immediate fixes. +- Do not collect private student or school data. +- Do not ask attendees for broad unpaid curriculum work. + +Suggested structure: + +1. State current project stage. +2. Answer setup or demo questions. +3. Point people to one relevant starter issue. +4. Record unresolved questions as issues or discussion follow-ups. + +## First Educator Review Session Plan + +Scope: +- Review one learner flow, not the entire curriculum. + +Length: 30 to 45 minutes + +Prep: +- Share [public-demo.md](public-demo.md). +- Share [community-trust.md](community-trust.md). +- Clarify that participation is optional, bounded, and unpaid unless otherwise stated. +- Ask whether feedback may be credited. + +Questions: +- What learner age or context are you imagining? +- What felt useful or promising? +- What felt unclear, culturally off, inaccessible, or age-inappropriate? +- What would need to change before classroom use? +- What source, activity, or facilitation support is missing? + +Follow-up: +- Summarize feedback in a GitHub issue if appropriate. +- Mark historical/source concerns separately. +- Ask before naming the reviewer publicly. diff --git a/docs/phase-2-feedback-triage.md b/docs/phase-2-feedback-triage.md new file mode 100644 index 0000000..2fec697 --- /dev/null +++ b/docs/phase-2-feedback-triage.md @@ -0,0 +1,85 @@ +# Phase 2 Feedback Collection and Triage + +Use these questions and rules to turn early feedback into useful work without overclaiming readiness. + +## Educator Feedback Questions + +- What grade band or learner context are you imagining? +- Which demo role, route, lesson, or activity did you review? +- What felt useful for learners? +- What felt confusing or too advanced? +- What felt culturally strong? +- What felt culturally off, thin, or overgeneralized? +- What source, activity, image, prompt, or teacher support would help? +- What accessibility or learner-support concerns did you notice? +- What would you need before using this in a classroom, homeschool, or learning group? +- Are you comfortable being credited if this feedback leads to a visible change? + +## Developer Feedback Questions + +- Could you understand what EchoEd is from the README? +- Could you identify how to run frontend and backend locally? +- Did `CONTRIBUTING.md` make the first contribution path clear? +- Did `ARCHITECTURE.md` help you find the relevant files? +- Were starter issues clear enough to begin? +- Which setup step was confusing? +- Which test or validation command was unclear? +- What would make the first PR easier? + +## Demo Feedback Questions + +- Which role did you try? +- Was the demo credential warning clear? +- Was it obvious where to start? +- What part of the navigation was confusing? +- What made the project feel trustworthy? +- What made it feel unfinished or risky? +- What one change would most improve the first impression? + +## Triage Categories + +Classify feedback as one of: + +- `bug` +- `documentation` +- `accessibility` +- `curriculum` +- `historical accuracy` +- `onboarding` +- `demo` +- `roadmap` +- `discussion follow-up` +- `no action` + +## Triage Rules + +- Create a GitHub issue when feedback is specific, actionable, and not already tracked. +- Add to the roadmap when feedback is useful but larger than a small issue. +- Use GitHub Discussions when feedback is exploratory or needs community input. +- Mark as `historical accuracy` when source, framing, geography, dates, people, or interpretation are questioned. +- Mark as `accessibility` when feedback affects keyboard use, screen readers, readability, color, mobile layout, or cognitive load. +- Use `no action` only when the feedback is not actionable, is outside scope, or duplicates a tracked issue. + +## Overclaiming Guardrails + +Do not say: +- classroom-ready +- historically reviewed +- educator-approved +- culturally complete +- production-ready + +Use more accurate language: +- early demo +- ready for bounded review +- needs educator feedback +- needs historical/source review +- contributor-ready for small issues + +## Recognition Check + +Before public credit, ask: + +```text +Would you like to be credited if this feedback leads to a visible change? Options: yes, no, or ask me first. +``` diff --git a/docs/phase-2-outreach-assets.md b/docs/phase-2-outreach-assets.md new file mode 100644 index 0000000..e8b6c18 --- /dev/null +++ b/docs/phase-2-outreach-assets.md @@ -0,0 +1,233 @@ +# Phase 2 Outreach Assets + +These templates are for careful, organic outreach. Do not mass-send them. Personalize each message and keep the ask bounded. + +## Shared Language + +Use this short project description when helpful: + +```text +EchoEd is an early open-source education platform centered on African and African-American history. It has a working K-5 demo and is looking for bounded educator feedback, contributor help, and community guidance before broader outreach. +``` + +Use this safety note when linking the demo: + +```text +The demo uses shared demo-only credentials. Please do not enter personal, student, school, or production data. +``` + +## Educator Outreach Message + +```text +Hi [Name], + +I am preparing EchoEd, an early open-source education platform centered on African and African-American history, for careful community review. + +I am not asking for a full curriculum review. If you are open to it, I would value 15-20 minutes of bounded feedback on one K-5 learner demo flow: what feels useful, unclear, culturally off, age-inappropriate, inaccessible, or missing for classroom use. + +The project is no-budget and early, so I want to be transparent about the ask. Feedback can be credited only if you want that. + +Demo guide: [link] +GitHub repo: [link] + +Would you be open to reviewing one learner flow or pointing me toward someone who might be interested? +``` + +## HBCU Outreach Message + +```text +Hello [Name], + +I am building EchoEd, an early open-source education platform centered on African and African-American history. The project has a working K-5 demo and is preparing for careful public feedback before broader outreach. + +I am reaching out to see whether this could be relevant to [department/program/chapter] for a bounded review, student open-source contribution, digital humanities discussion, or education technology feedback. + +The immediate asks are small: +- educators: review one demo flow for classroom usefulness and cultural framing +- developers/students: test setup, review docs, or pick a small starter issue + +There is no paid program or formal partnership implied. I am looking for respectful feedback and possible contributors. + +Repo: [link] +Demo guide: [link] + +Would there be a better person or student group to contact? +``` + +## Developer Contributor Invitation + +```text +Hi [Name], + +I am preparing EchoEd for its first open-source contributors. EchoEd is an Angular/FastAPI education platform centered on African and African-American history, with a working K-5 demo. + +I am looking for developers willing to test contributor onboarding or pick up small starter issues in docs, frontend polish, accessibility, backend tests, or demo reliability. + +The ask is bounded: one setup pass, one issue, or one piece of feedback on the contribution flow. + +Repo: [link] +Contributing guide: [link] +Starter issue drafts: [link] + +Would you be open to taking a look or sharing it with someone who likes early open-source education projects? +``` + +## Open-Source Contributor Message + +```text +Hi [Name], + +I am looking for feedback on EchoEd's first-contributor experience. EchoEd is an early open-source education platform centered on African and African-American history. + +I am especially interested in whether the README, CONTRIBUTING guide, issue templates, and starter issues make it clear how someone can help without needing maintainer context. + +If you have 10-15 minutes, could you review the contributor path and tell me where it feels unclear? + +Repo: [link] +``` + +## Africa or Caribbean Contact Message + +```text +Hi [Name], + +I am preparing EchoEd, an early open-source platform for African and African-American history learning, for careful community review. + +Because the project touches African, African-American, Caribbean, and diaspora learning contexts, I want to avoid narrow framing and invite bounded feedback from people with relevant education, history, or technology perspectives. + +The ask is small: review one demo path, one docs page, or the way the project describes community review. + +Repo: [link] +Demo guide: [link] + +Would this be relevant to you or someone in your network? +``` + +## Community Organizer Message + +```text +Hi [Name], + +I am preparing EchoEd for early community engagement. It is an open-source education platform centered on African and African-American history, currently at the working K-5 demo stage. + +I am looking for careful introductions, not mass promotion: Black educators, HBCU education or CS programs, Black developers, homeschool/community learning groups, and Africa or Caribbean education technology contacts. + +If you are open to it, I would appreciate one suggested person, group, or channel where a bounded demo review request would be appropriate. + +Project: [link] +``` + +## Educator Interview Request + +```text +Hi [Name], + +Would you be open to a 20-30 minute conversation about EchoEd's K-5 demo and what educators would need before trusting or using a tool like this? + +This is not a request for unpaid curriculum development. I would ask a small set of questions about classroom usefulness, cultural framing, accessibility, and what would make the demo more trustworthy. + +You can choose whether any feedback is credited publicly. + +If that is too much right now, a short written note on one demo flow would also help. +``` + +## LinkedIn Launch Post + +```text +I am opening up EchoEd for careful early community review. + +EchoEd is an early open-source education platform centered on African and African-American history. It has a working K-5 demo with student, teacher, and admin experiences. + +The goal right now is not mass marketing. It is bounded, respectful feedback and first contributors. + +I am looking for: +- Black educators and African-American studies educators to review one learner flow +- HBCU education and CS programs interested in feedback or starter open-source contributions +- Black software developers and open-source contributors interested in docs, frontend, backend, accessibility, tests, or demo reliability +- Africa and Caribbean education/history/technology perspectives to help avoid narrow framing + +The project is early and no-budget. Any ask should be specific, optional, and credited only if people want recognition. + +Repo: [link] +Demo guide: [link] + +If you know someone who would be a thoughtful reviewer or contributor, I would appreciate an introduction. +``` + +## GitHub Discussions Welcome Post + +```text +Welcome to EchoEd. + +EchoEd is an early open-source education platform centered on African and African-American history. We are starting with careful community review before broad outreach. + +Useful first paths: +- Educators: try one learner demo flow and share bounded feedback. +- Developers: review CONTRIBUTING.md, test setup, or pick a starter issue. +- Organizers: suggest respectful places where a bounded review request would be welcome. +- Reviewers: flag accessibility, historical accuracy, source, or cultural framing concerns. + +Important: the public demo uses shared demo-only credentials. Do not enter real student, school, personal, or production data. + +Current needs: +- educator feedback on one K-5 learner flow +- developer review of setup and first contribution flow +- accessibility review of landing/demo entry +- historical/source review process feedback + +Please introduce yourself only if you want to. Participation is optional and bounded. +``` + +## Dev.to Article Outline + +Title: Building open-source education infrastructure for African and African-American history + +Outline: + +1. Why EchoEd exists + - culturally grounded learning + - open-source ownership + - why trust comes before scale +2. What exists today + - K-5 demo + - student, teacher, admin experiences + - public docs and contribution flow +3. What Phase 1 prepared + - README, contributing guide, trust docs, demo guide + - issue templates and PR template +4. What Phase 2 needs + - bounded educator feedback + - first developer contributors + - accessibility review + - historical accuracy/source review +5. How developers can help + - docs + - frontend + - backend tests + - demo reliability + - accessibility +6. How educators can help + - review one flow + - share classroom concerns + - suggest source/framing improvements +7. Closing ask + - try the demo + - open one issue + - share with one thoughtful reviewer + +## Reddit-Safe Discussion Post + +```text +I am looking for feedback, not promotion. + +I am building EchoEd, an early open-source education platform centered on African and African-American history. It has a working K-5 demo and public docs, but no users or contributors yet. + +Before I do broader outreach, I am trying to understand what would make a project like this trustworthy to educators and approachable for open-source contributors. + +Questions: +- What would you need to see before taking an education demo seriously? +- What makes an open-source education project feel contributor-ready? +- What are common mistakes when asking educators for feedback? + +If linking the repo is allowed here, I can share it. If not, general advice is still useful. +``` diff --git a/docs/phase-2-outreach-tracker.md b/docs/phase-2-outreach-tracker.md new file mode 100644 index 0000000..776ce47 --- /dev/null +++ b/docs/phase-2-outreach-tracker.md @@ -0,0 +1,65 @@ +# Phase 2 Outreach Tracker Guide + +Do not commit real contact lists, email addresses, private notes, or sensitive relationship data to this repository. Use this guide to create a private spreadsheet or local tracker. + +## Suggested Columns + +| Column | Purpose | +| --- | --- | +| Target | Organization, group, or person name | +| Contact | Public contact route or private contact stored outside the repo | +| Region | United States, Africa, Caribbean, or other | +| Audience | Educator, HBCU, developer, open-source, organizer, advisor, student | +| Channel | Email, LinkedIn, GitHub, introduction, event, forum | +| Ask | Demo review, setup review, starter issue, intro, interview, discussion | +| Status | Current lifecycle stage | +| Last contact date | Date of last outreach or reply | +| Next follow-up date | Date for one bounded follow-up | +| Owner | Maintainer responsible for follow-up | +| Outcome | Result category | +| Notes | Keep brief; do not store sensitive data | + +## Status Lifecycle + +- `identified`: target found but not contacted +- `drafted`: message drafted but not sent +- `contacted`: first message sent +- `replied`: received a reply +- `scheduled`: call, walkthrough, or review scheduled +- `contributed feedback`: feedback received +- `converted to issue`: feedback became GitHub issue or roadmap item +- `declined`: person or group declined +- `no response`: no reply after bounded follow-up +- `closed`: no further action planned + +## Follow-Up Cadence + +Use a low-pressure cadence: + +1. Initial contact. +2. One follow-up after 7 to 10 days if there is no reply. +3. Close as `no response` after another 10 to 14 days. + +Do not repeatedly follow up. Do not pressure people to contribute. + +## Outcome Categories + +- `no response` +- `replied` +- `demo reviewed` +- `issue created` +- `contributor lead` +- `educator feedback` +- `advisor interest` +- `intro offered` +- `not a fit` +- `follow later` +- `closed` + +## Privacy Rules + +- Do not commit the tracker. +- Do not commit private email addresses or phone numbers. +- Do not record sensitive personal details. +- Keep notes factual and minimal. +- Respect requests not to be contacted again. diff --git a/docs/phase-2-starter-issues.md b/docs/phase-2-starter-issues.md new file mode 100644 index 0000000..9e8963c --- /dev/null +++ b/docs/phase-2-starter-issues.md @@ -0,0 +1,182 @@ +# Phase 2 Starter Issue Drafts + +Use these drafts to manually create the first GitHub issues after labels are configured. Do not create issues automatically unless maintainers explicitly choose to use GitHub tooling. + +## Before Creating Issues + +- Create the labels recommended in [github-community-setup.md](github-community-setup.md). +- Keep issue scope small enough for a first contribution. +- Link to relevant docs when possible. +- Do not assign issues to people unless they ask. + +## Draft 1: Good First Issue - Verify Windows Setup Instructions + +Recommended labels: `good first issue`, `documentation`, `contributor onboarding`, `needs triage` + +### Context + +EchoEd's docs include Windows-focused setup commands. A new contributor should be able to follow them without private maintainer help. + +### Issue Body + +Review the setup instructions in `README.md`, `CONTRIBUTING.md`, and `ARCHITECTURE.md` from the perspective of a first-time Windows contributor. + +### Acceptance Criteria + +- Confirm frontend setup commands are clear. +- Confirm backend setup commands are clear. +- Note any command that fails or needs extra context. +- Suggest doc edits if something is confusing. +- Do not change product code. + +### Validation + +- Run only the commands you are comfortable running. +- If a command cannot be run, note why in the issue. + +## Draft 2: Educator Feedback - Review One Student Demo Flow + +Recommended labels: `educator feedback`, `curriculum`, `demo`, `needs educator review` + +### Context + +EchoEd needs bounded educator feedback before broader outreach. This issue asks for review of one learner flow, not the full platform. + +### Issue Body + +Use [public-demo.md](public-demo.md) to sign in as `normalstudent` and review one learner path. + +### Review Prompts + +- What grade band or learner context are you using? +- What felt clear or useful? +- What felt confusing, inaccessible, or culturally off? +- What would an educator need before using this with learners? +- What discussion prompt, activity support, or source would improve the flow? + +### Recognition + +Please state whether you are comfortable being credited if your feedback leads to a visible change. + +### Acceptance Criteria + +- Feedback identifies the reviewed route or lesson. +- Feedback includes at least one concrete improvement or concern. +- Feedback avoids entering real learner data. + +## Draft 3: Documentation - Improve Public Demo Guide Screenshots or Walkthrough + +Recommended labels: `documentation`, `demo`, `good first issue`, `needs maintainer review` + +### Context + +The public demo guide is text-only. A contributor can improve evaluation by adding a clearer walkthrough outline or screenshot checklist. + +### Issue Body + +Review [public-demo.md](public-demo.md) and suggest additions that help educators, developers, and organizers understand what to evaluate. + +### Acceptance Criteria + +- Add or propose a short step-by-step walkthrough for at least one role. +- Include screenshot placeholders or a screenshot checklist if actual screenshots are not added. +- Keep demo credential warnings visible. +- Do not add private data or real student information. + +### Validation + +- Confirm all links in the guide still resolve. +- Confirm the guide remains readable for non-technical educators. + +## Draft 4: Accessibility/UI Review - Landing Page and Demo Entry + +Recommended labels: `accessibility`, `frontend`, `demo`, `needs accessibility review` + +### Context + +Before inviting more visitors, EchoEd needs a lightweight accessibility and UI review of the landing page and demo entry path. + +### Issue Body + +Review the public landing page and login/demo entry path for keyboard use, readable text, contrast, labels, mobile layout, and clear calls to action. + +### Acceptance Criteria + +- Note any keyboard navigation issues. +- Note any contrast or readability issues. +- Note any confusing call to action. +- Include browser/device context. +- File follow-up issues for specific fixes if needed. + +### Validation + +- Manual review is acceptable. +- Screenshots are helpful but not required. + +## Draft 5: Contributor Onboarding - Test First PR Flow + +Recommended labels: `contributor onboarding`, `documentation`, `good first issue`, `needs maintainer review` + +### Context + +EchoEd needs to know whether a first-time contributor can understand how to pick an issue, make a small docs change, and open a pull request. + +### Issue Body + +Follow [CONTRIBUTING.md](../CONTRIBUTING.md) and identify any friction in the first contribution workflow. + +### Acceptance Criteria + +- Identify one place the contributor workflow is clear. +- Identify one place it could be clearer. +- Suggest a specific doc improvement. +- Do not change application behavior. + +### Validation + +- A documentation-only pull request or comment with recommended edits is acceptable. + +## Draft 6: Historical Accuracy Review - Source and Framing Path + +Recommended labels: `historical accuracy`, `curriculum`, `needs historical review` + +### Context + +EchoEd needs a clear process for historical accuracy and source concerns before scaling educator outreach. + +### Issue Body + +Review [community-trust.md](community-trust.md) and the historical accuracy issue template. Identify whether the path is clear for reporting source, framing, or accuracy concerns. + +### Acceptance Criteria + +- Confirm whether the reporting path is understandable. +- Suggest missing context or clarifying language. +- Do not require reviewers to provide unpaid source research. + +### Validation + +- Documentation review only. + +## Draft 7: Good First Issue - Add Five More Starter Issue Candidates + +Recommended labels: `good first issue`, `documentation`, `help wanted` + +### Context + +Phase 2 starts with a small issue set. More starter issues will help match contributors with clear work. + +### Issue Body + +Add five additional starter issue drafts to this document or propose them in a comment. + +### Acceptance Criteria + +- Each issue has title, labels, context, acceptance criteria, and validation. +- At least one issue is educator-facing. +- At least one issue is developer-facing. +- At least one issue is accessibility or documentation focused. + +### Validation + +- Maintainer can manually create the issue from the draft without asking for missing scope. diff --git a/openspec/changes/activate-community-outreach/.openspec.yaml b/openspec/changes/activate-community-outreach/.openspec.yaml new file mode 100644 index 0000000..074342d --- /dev/null +++ b/openspec/changes/activate-community-outreach/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-07-09 diff --git a/openspec/changes/activate-community-outreach/design.md b/openspec/changes/activate-community-outreach/design.md new file mode 100644 index 0000000..9050936 --- /dev/null +++ b/openspec/changes/activate-community-outreach/design.md @@ -0,0 +1,111 @@ +## Context + +Phase 1 established EchoEd's public open-source readiness foundation: README, contributor guide, code of conduct, roadmap, architecture overview, security policy, public demo guide, community trust guide, outreach readiness guide, GitHub issue templates, PR template, and the `open-source-community-readiness` spec. + +Phase 2 starts from zero traction. EchoEd has no current public users, contributors, stars, advisors, or community routines. The goal is not broad promotion; it is careful activation: create a small set of visible starter issues, prepare respectful outreach assets, enable basic community surfaces, run a first demo/review routine, and turn early feedback into issues or roadmap items. + +Important constraints: + +- No paid budget. +- No outreach automation. +- No scraping. +- No contacting anyone as part of implementation. +- No private or sensitive contact data committed to the repo. +- No claim that EchoEd is classroom-ready before educator and historical review. +- Manual GitHub owner tasks remain manual: labels, Discussions, categories, and issue creation if API tooling is not used. + +## Goals / Non-Goals + +**Goals:** + +- Provide at least 5 starter issue drafts that are ready to create in GitHub. +- Provide copy-ready outreach templates for educators, HBCUs, developers, open-source contributors, Africa/Caribbean contacts, and community organizers. +- Provide copy-ready launch content for LinkedIn, GitHub Discussions, Dev.to, and Reddit-safe discussion. +- Define a simple contact tracker structure and status lifecycle without storing real contacts. +- Define a first community launch workflow: GitHub Discussions, welcome post, demo walkthrough, office hours, and educator review session. +- Define feedback questions and triage rules that convert feedback into GitHub issues or roadmap items. +- Define recognition and trust practices for the first contributors, educators, and advisors. +- Define a 30-day execution plan with low-volume daily outreach and zero-traction success metrics. + +**Non-Goals:** + +- No automated emailing, social posting, scraping, or CRM integration. +- No paid marketing, sponsorships, ads, or influencer campaigns. +- No creation of real contact lists in the repository. +- No application feature work. +- No production user onboarding. +- No guarantee of contributor response, educator participation, or public adoption. + +## Decisions + +### Decision: Use repository docs as reusable outreach assets + +Phase 2 will add docs containing copy-ready outreach language, issue drafts, feedback questions, and workflow guidance. This keeps materials visible, reviewable, and easy to revise. + +Alternatives considered: + +- Keep outreach copy in private notes only. Rejected because the project benefits from transparent messaging and maintainer reuse. +- Add a CRM or contact-management tool. Rejected because the project has no traction, no budget, and no need to store private data in this phase. + +### Decision: Draft starter issues rather than create issues automatically + +Implementation will provide issue drafts with titles, labels, body copy, and acceptance criteria. Maintainers can create them manually in GitHub after labels are configured. + +Alternatives considered: + +- Use GitHub CLI or API to create issues automatically. Rejected because `gh` is not installed in the current environment and automation is not necessary for Phase 2. +- Store starter issues only as a list of titles. Rejected because first contributors need enough acceptance criteria to act. + +### Decision: Treat GitHub Discussions as a manual launch surface + +The change will include welcome discussion copy and category recommendations, but enabling Discussions remains a manual GitHub owner task. + +Alternatives considered: + +- Use only issues for all community interaction. Rejected because intros, Q&A, and broader educator/developer conversation can overwhelm issue tracking. +- Launch Discord or Slack immediately. Rejected because moderation overhead is too high before there is a community. + +### Decision: Use bounded outreach routines + +The 30-day plan will favor small daily actions, warm introductions, and concrete asks such as "review one learner flow" or "test setup and file one issue." + +Alternatives considered: + +- Mass post across many communities. Rejected because the project is zero-traction and culturally specific; trust matters more than volume. +- Wait for contributors organically without outreach. Rejected because early visibility requires deliberate invitations. + +### Decision: Keep recognition opt-in and transparent + +Recognition guidance will let contributors and educators opt into credit without implying employment, compensation, formal advisor status, or ongoing labor expectations. + +Alternatives considered: + +- Publicly credit all feedback by default. Rejected because some reviewers may not want visibility. +- Avoid recognition until formal governance exists. Rejected because early contributors deserve visible appreciation when they want it. + +## Risks / Trade-offs + +- [Risk] Outreach messages may still feel extractive. -> Mitigation: include non-extractive language, bounded asks, no-budget transparency, and opt-in recognition. +- [Risk] Starter issues may attract attention before maintainers are ready. -> Mitigation: include manual readiness checks and label setup before issue creation. +- [Risk] GitHub Discussions may create moderation overhead. -> Mitigation: recommend enabling only when maintainers can respond and start with narrow categories. +- [Risk] Public demo credentials may be misused after outreach. -> Mitigation: repeat demo-only warnings in outreach assets and feedback prompts. +- [Risk] Contact tracking could become sensitive. -> Mitigation: define structure only; do not commit real contacts or private notes. +- [Risk] Success metrics may become vanity metrics. -> Mitigation: focus on replies, feedback quality, issues created, demo review sessions, and first contributor activation rather than follower counts. + +## Migration Plan + +1. Add Phase 2 outreach activation docs and starter issue drafts. +2. Keep all real outreach execution manual and outside the repository. +3. Validate OpenSpec change with `openspec validate activate-community-outreach --strict`. +4. When implemented, manually configure GitHub labels and Discussions before creating starter issues. +5. Create starter issues manually from the drafts. +6. Run the 30-day plan using an external spreadsheet or private tracker, not committed repo data. + +Rollback is documentation-only: revert the Phase 2 docs/change files if they are not useful. No runtime or data migration is involved. + +## Open Questions + +- Which public contact address should be final for community scheduling if `support@echoed.com` changes? +- Will GitHub Discussions be enabled before the first outreach messages or after the first small review cohort? +- Who will own weekly triage of educator feedback and developer issues during the first 30 days? +- Should the first office hours session be asynchronous in GitHub Discussions or live over video? diff --git a/openspec/changes/activate-community-outreach/proposal.md b/openspec/changes/activate-community-outreach/proposal.md new file mode 100644 index 0000000..01cff3b --- /dev/null +++ b/openspec/changes/activate-community-outreach/proposal.md @@ -0,0 +1,47 @@ +## Why + +Phase 1 made EchoEd ready for public open-source outreach; Phase 2 turns that readiness into careful first engagement. EchoEd needs a practical, organic outreach activation plan that creates starter issues, copy-ready outreach assets, feedback loops, and a 30-day execution workflow without mass marketing, scraping, paid promotion, or storing private contact data in the repository. + +## What Changes + +- Define Phase 2 as outreach activation and first community engagement. +- Create a starter-issue plan with at least 5 initial issue candidates across good-first-issue, educator feedback, documentation, accessibility or UI review, and contributor onboarding. +- Add outreach assets for respectful organic outreach: + - copy-ready outreach message templates + - LinkedIn launch post + - GitHub Discussions welcome post + - Dev.to article outline + - Reddit-safe discussion post + - HBCU outreach message + - educator interview request message + - developer contributor invitation message +- Define a contact tracking structure with suggested columns, status lifecycle, follow-up cadence, and outcome categories. +- Define the community launch workflow: + - enable GitHub Discussions manually + - configure recommended discussion categories + - publish the first welcome discussion + - plan the first demo walkthrough + - plan the first office hours session + - plan the first educator review session +- Define feedback collection flows for educators, developers, and demo reviewers, including how feedback becomes GitHub issues or roadmap items. +- Define recognition and trust practices for contributors, educators, advisors, and reviewers without implying unpaid labor obligations or guaranteed formal roles. +- Add a 30-day execution plan with week-by-week actions, minimum daily outreach routine, first 10 target audiences, and success metrics appropriate for a zero-traction starting point. +- Include manual setup reminders for GitHub labels and Discussions. +- No outreach automation, scraping, paid marketing, contact import, private CRM data, or actual outreach execution is included. + +## Capabilities + +### New Capabilities + +- `community-outreach-activation`: Defines EchoEd's first organic outreach activation process, including starter issues, outreach assets, discussion launch, feedback collection, trust practices, tracking structure, and 30-day execution plan. + +### Modified Capabilities + +- None. + +## Impact + +- Affected repository files: new docs and issue-starter assets for outreach activation. +- Affected GitHub setup: manual labels, GitHub Discussions enablement, discussion categories, and starter issue creation. +- Affected community process: first outreach messages, review sessions, office hours, feedback triage, recognition, and outcome tracking. +- No code, API, database, auth, deployment, scraping, automation, paid tooling, or real contact data changes. diff --git a/openspec/changes/activate-community-outreach/specs/community-outreach-activation/spec.md b/openspec/changes/activate-community-outreach/specs/community-outreach-activation/spec.md new file mode 100644 index 0000000..3dbd95f --- /dev/null +++ b/openspec/changes/activate-community-outreach/specs/community-outreach-activation/spec.md @@ -0,0 +1,121 @@ +## ADDED Requirements + +### Requirement: Starter Issue Activation +EchoEd SHALL provide a practical starter-issue package before Phase 2 outreach begins. + +#### Scenario: Starter issue drafts exist +- **WHEN** Phase 2 implementation is complete +- **THEN** the repository contains at least 5 starter issue drafts with titles, recommended labels, context, acceptance criteria, and validation steps + +#### Scenario: Starter issues cover first engagement paths +- **WHEN** maintainers review starter issue drafts +- **THEN** the drafts include good-first-issue candidates, educator feedback issues, documentation improvement issues, accessibility or UI review issues, and contributor onboarding issues + +#### Scenario: Starter issues are manually creatable +- **WHEN** GitHub labels are configured +- **THEN** maintainers can manually create starter issues from the drafts without needing automation or private contact data + +### Requirement: Outreach Asset Package +EchoEd SHALL provide copy-ready outreach assets for careful, organic community engagement. + +#### Scenario: Outreach templates are available +- **WHEN** maintainers prepare first outreach +- **THEN** they can use copy-ready messages for HBCUs, educators, developer contributors, open-source contributors, Africa or Caribbean contacts, and community organizers + +#### Scenario: Launch content is available +- **WHEN** maintainers prepare public launch posts +- **THEN** the repository provides a LinkedIn launch post, GitHub Discussions welcome post, Dev.to article outline, and Reddit-safe discussion post + +#### Scenario: Outreach copy is bounded and respectful +- **WHEN** a maintainer uses a Phase 2 outreach template +- **THEN** the message includes a specific ask, current project stage, no-budget transparency where relevant, demo/data safety language where relevant, and no implication of unpaid labor obligation + +### Requirement: Contact Tracking Guidance +EchoEd SHALL define a simple outreach tracker structure without storing private contact data in the repository. + +#### Scenario: Tracker columns are documented +- **WHEN** maintainers create a private tracker +- **THEN** they can use documented columns for target, contact, region, audience, channel, ask, status, next step, owner, follow-up date, and outcome + +#### Scenario: Status lifecycle is defined +- **WHEN** maintainers update outreach status +- **THEN** they can use a lifecycle including identified, drafted, contacted, replied, scheduled, contributed feedback, converted to issue, declined, no response, and closed + +#### Scenario: Follow-up cadence is bounded +- **WHEN** a contact does not respond +- **THEN** the tracker guidance limits follow-up cadence and avoids repeated pressure + +### Requirement: Community Launch Workflow +EchoEd SHALL define the first manual community launch workflow. + +#### Scenario: GitHub Discussions setup is specified +- **WHEN** maintainers are ready to open community discussion +- **THEN** Phase 2 guidance reminds them to enable GitHub Discussions manually and configure categories for announcements, introductions, Q&A, educator feedback, contributor help, roadmap, and show-and-tell + +#### Scenario: First welcome discussion is prepared +- **WHEN** GitHub Discussions is enabled +- **THEN** maintainers have copy-ready welcome discussion content that introduces EchoEd, current stage, demo path, contribution paths, and community expectations + +#### Scenario: First engagement sessions are planned +- **WHEN** maintainers schedule first community activities +- **THEN** Phase 2 guidance provides a demo walkthrough plan, office hours plan, and educator review session plan + +### Requirement: Feedback Collection and Triage +EchoEd SHALL provide feedback prompts and triage rules for early reviewers. + +#### Scenario: Feedback questions are available +- **WHEN** educators, developers, or demo reviewers evaluate EchoEd +- **THEN** maintainers can ask role-appropriate feedback questions for educator review, developer onboarding, and demo experience + +#### Scenario: Feedback becomes tracked work +- **WHEN** useful feedback is received +- **THEN** maintainers can classify it as bug, documentation, accessibility, curriculum, historical accuracy, onboarding, demo, roadmap, or discussion follow-up + +#### Scenario: Feedback triage avoids overclaiming +- **WHEN** feedback suggests classroom or historical readiness concerns +- **THEN** maintainers record the concern without claiming classroom readiness or historical authority until review is complete + +### Requirement: Recognition and Trust +EchoEd SHALL define transparent recognition and participation expectations for first community engagement. + +#### Scenario: Recognition is opt-in +- **WHEN** contributors, educators, or advisors provide meaningful help +- **THEN** maintainers ask whether and how they want to be credited before public recognition + +#### Scenario: Advisor language is accurate +- **WHEN** maintainers discuss advisor or educator participation +- **THEN** they distinguish informal feedback, advisory-circle interest, and any future formal role + +#### Scenario: Participation expectations are transparent +- **WHEN** outreach templates or session plans ask for help +- **THEN** they make clear that participation is optional, bounded, unpaid unless otherwise stated, and not an ongoing obligation + +### Requirement: Thirty-Day Organic Execution Plan +EchoEd SHALL define a 30-day outreach activation plan appropriate for a zero-traction starting point. + +#### Scenario: Week-by-week plan exists +- **WHEN** maintainers begin Phase 2 +- **THEN** they can follow a week-by-week plan covering setup, first direct outreach, first feedback sessions, issue conversion, and review of results + +#### Scenario: Daily routine is bounded +- **WHEN** maintainers execute outreach on a normal day +- **THEN** the plan defines a minimum daily routine that can be completed without paid tools or high-volume posting + +#### Scenario: First target audiences are identified +- **WHEN** maintainers choose first outreach targets +- **THEN** the plan lists 10 target audience types spanning educators, HBCUs, Black developers, Africa and Caribbean contributors, open-source contributors, and community organizers + +#### Scenario: Zero-traction metrics are defined +- **WHEN** maintainers evaluate the first 30 days +- **THEN** they measure practical early indicators such as outreach sent, replies, demo reviews, issues created, first contributors, educator feedback quality, and follow-up conversations rather than vanity metrics alone + +### Requirement: Manual Setup and Validation +EchoEd SHALL define manual setup reminders and validation steps for Phase 2. + +#### Scenario: Manual GitHub setup reminders are present +- **WHEN** maintainers prepare to activate outreach +- **THEN** guidance reminds them to create GitHub labels, enable Discussions, configure discussion categories, and create starter issues manually if no CLI tooling is available + +#### Scenario: Phase 2 validation is defined +- **WHEN** Phase 2 artifacts are complete +- **THEN** maintainers can validate OpenSpec, review docs for placeholders and private contact data, verify internal links, and confirm no automation or paid marketing assumptions were introduced diff --git a/openspec/changes/activate-community-outreach/tasks.md b/openspec/changes/activate-community-outreach/tasks.md new file mode 100644 index 0000000..d20b52c --- /dev/null +++ b/openspec/changes/activate-community-outreach/tasks.md @@ -0,0 +1,65 @@ +## 1. Starter Issue Package + +- [x] 1.1 Create a Phase 2 starter issue draft document under `docs/` with at least 5 issue drafts. +- [x] 1.2 Include good-first-issue candidates with title, labels, context, acceptance criteria, and validation. +- [x] 1.3 Include educator feedback issue drafts with bounded review prompts and recognition language. +- [x] 1.4 Include documentation improvement issue drafts for setup, demo, or outreach docs. +- [x] 1.5 Include accessibility or UI review issue drafts for landing/demo review. +- [x] 1.6 Include contributor onboarding issue drafts for setup friction and first PR flow. + +## 2. Outreach Asset Package + +- [x] 2.1 Create a Phase 2 outreach assets document under `docs/`. +- [x] 2.2 Add copy-ready direct outreach message templates for educators, HBCUs, developers, open-source contributors, Africa or Caribbean contacts, and community organizers. +- [x] 2.3 Add a LinkedIn launch post that explains the mission, current stage, demo path, and bounded asks. +- [x] 2.4 Add a GitHub Discussions welcome post for first community activation. +- [x] 2.5 Add a Dev.to article outline focused on building open-source education infrastructure for African and African-American history. +- [x] 2.6 Add a Reddit-safe discussion post that invites feedback without promotional tone. +- [x] 2.7 Add HBCU outreach, educator interview request, and developer contributor invitation messages. + +## 3. Contact Tracking Guidance + +- [x] 3.1 Create a Phase 2 outreach tracker guide that defines columns without storing real contacts. +- [x] 3.2 Define status lifecycle values from identified through closed. +- [x] 3.3 Define a bounded follow-up cadence that avoids pressure or spam. +- [x] 3.4 Define outcome categories such as no response, replied, demo reviewed, issue created, contributor lead, educator feedback, advisor interest, and not a fit. + +## 4. Community Launch Workflow + +- [x] 4.1 Document manual GitHub Discussions enablement and recommended categories. +- [x] 4.2 Add first welcome discussion copy. +- [x] 4.3 Add first demo walkthrough plan with audience, agenda, prep, and follow-up. +- [x] 4.4 Add first office hours plan with format options and boundaries. +- [x] 4.5 Add first educator review session plan with bounded review scope and feedback routing. + +## 5. Feedback Collection and Triage + +- [x] 5.1 Add educator feedback questions for lesson flow, age fit, classroom usefulness, cultural framing, source needs, and accessibility. +- [x] 5.2 Add developer feedback questions for setup, architecture clarity, tests, starter issues, and contribution friction. +- [x] 5.3 Add demo feedback questions for role clarity, navigation, usefulness, trust, and confusion points. +- [x] 5.4 Define triage rules that convert feedback into GitHub issues, roadmap items, discussion follow-ups, or no-action notes. +- [x] 5.5 Ensure triage guidance avoids claims of classroom or historical readiness before review. + +## 6. Recognition and Trust + +- [x] 6.1 Define contributor recognition options for first PRs, docs feedback, accessibility review, and demo feedback. +- [x] 6.2 Define educator/advisor credit options with opt-in language. +- [x] 6.3 Add non-extractive participation language for outreach assets and sessions. +- [x] 6.4 State that participation is optional, bounded, and unpaid unless explicitly stated otherwise. +- [x] 6.5 Document transparent contribution expectations and maintainer response limits. + +## 7. Thirty-Day Execution Plan + +- [x] 7.1 Create a 30-day execution plan with week-by-week actions. +- [x] 7.2 Define a minimum daily outreach routine that can be done without paid tools. +- [x] 7.3 List the first 10 target audience types for early outreach. +- [x] 7.4 Define zero-traction success metrics for the first 30 days. +- [x] 7.5 Include reminders to create GitHub labels and enable Discussions manually before launch posts. + +## 8. Validation + +- [x] 8.1 Run `openspec validate activate-community-outreach --strict`. +- [x] 8.2 Review Phase 2 docs for stale placeholders, private contact data, paid marketing assumptions, scraping, automation, or mass outreach instructions. +- [x] 8.3 Review internal links in new docs. +- [x] 8.4 Confirm no real outreach was performed and no private or sensitive contact data was added. +- [x] 8.5 Confirm no runtime, API, database, auth, or deployment behavior is changed by the proposal.