From c6c1c3d993aece8de17da1afa4b4f6529f80f6d8 Mon Sep 17 00:00:00 2001 From: OpenCode Date: Wed, 8 Jul 2026 15:26:39 +0700 Subject: [PATCH] Add 10 FAQ, policy, and writing guides Closes #481, Closes #482, Closes #483, Closes #484, Closes #485, Closes #486, Closes #487, Closes #488, Closes #489, Closes #490 --- docs/evidence/FAQ_CONTRIBUTOR.md | 20 +++++++++++++++++ docs/evidence/FAQ_MAINTAINER.md | 19 ++++++++++++++++ docs/evidence/FAQ_PUBLIC.md | 16 ++++++++++++++ docs/evidence/GUIDE_ASSUMPTIONS_REGISTER.md | 22 +++++++++++++++++++ docs/evidence/GUIDE_CLAIM_WORDING_STYLE.md | 22 +++++++++++++++++++ docs/evidence/GUIDE_DATA_SOURCE_DOCS.md | 24 +++++++++++++++++++++ docs/evidence/GUIDE_NO_HYPE_WRITING.md | 11 ++++++++++ docs/evidence/GUIDE_UNCERTAINTY_LANGUAGE.md | 17 +++++++++++++++ docs/evidence/POLICY_CITATION_SOURCE.md | 18 ++++++++++++++++ docs/evidence/POLICY_RETENTION.md | 18 ++++++++++++++++ tests/test_faq_writing_batch.py | 20 +++++++++++++++++ 11 files changed, 207 insertions(+) create mode 100644 docs/evidence/FAQ_CONTRIBUTOR.md create mode 100644 docs/evidence/FAQ_MAINTAINER.md create mode 100644 docs/evidence/FAQ_PUBLIC.md create mode 100644 docs/evidence/GUIDE_ASSUMPTIONS_REGISTER.md create mode 100644 docs/evidence/GUIDE_CLAIM_WORDING_STYLE.md create mode 100644 docs/evidence/GUIDE_DATA_SOURCE_DOCS.md create mode 100644 docs/evidence/GUIDE_NO_HYPE_WRITING.md create mode 100644 docs/evidence/GUIDE_UNCERTAINTY_LANGUAGE.md create mode 100644 docs/evidence/POLICY_CITATION_SOURCE.md create mode 100644 docs/evidence/POLICY_RETENTION.md create mode 100644 tests/test_faq_writing_batch.py diff --git a/docs/evidence/FAQ_CONTRIBUTOR.md b/docs/evidence/FAQ_CONTRIBUTOR.md new file mode 100644 index 00000000..b411a28e --- /dev/null +++ b/docs/evidence/FAQ_CONTRIBUTOR.md @@ -0,0 +1,20 @@ +# Contributor FAQ + +## How do I get started? +Read CONTRIBUTING.md, then QUICKSTART.md. Pick an issue from the open issues list. + +## What makes a good first issue? +Issues labeled `good-first-issue` are ideal. They're small, well-scoped, and don't require deep project knowledge. + +## How do I submit a PR? +1. Create a branch from main. +2. Make your change and add tests. +3. Run `python3 -m pytest -q` to verify. +4. Run `python3 scripts/check_doc_links.py` to check links. +5. Submit the PR referencing the issue number. + +## What if I get stuck? +Ask in the issue comments. If it's urgent, tag a maintainer. + +## Can I contribute without writing code? +Yes! Documentation improvements, test additions, and issue triage are all valuable. diff --git a/docs/evidence/FAQ_MAINTAINER.md b/docs/evidence/FAQ_MAINTAINER.md new file mode 100644 index 00000000..0583c868 --- /dev/null +++ b/docs/evidence/FAQ_MAINTAINER.md @@ -0,0 +1,19 @@ +# Maintainer FAQ + +## How do I merge a PR? +1. Ensure all checks pass. +2. Request review from at least one other maintainer for non-trivial changes. +3. Squash-merge with a descriptive commit message. +4. Delete the branch after merging. + +## How do I create a release? +1. Complete the release readiness checklist. +2. Create a release branch. +3. Run `make full-reproducibility-report`. +4. Tag the release and publish release notes. + +## How do I handle a safety issue? +1. Immediately flag the issue in the decision log. +2. Notify the project lead. +3. If needed, revert the unsafe change. +4. Document the resolution. diff --git a/docs/evidence/FAQ_PUBLIC.md b/docs/evidence/FAQ_PUBLIC.md new file mode 100644 index 00000000..22fbcffe --- /dev/null +++ b/docs/evidence/FAQ_PUBLIC.md @@ -0,0 +1,16 @@ +# Public FAQ for Non-Specialists + +## What is OpenAMP Foundry? +A computational pipeline that ranks antimicrobial peptide candidates before lab testing. + +## Does it discover new antibiotics? +It nominates candidates for testing. Discovery requires wet-lab validation. + +## Are the scores reliable? +They are predictions, not proof. The pipeline is benchmarked against known AMPs but has limitations (charge bias, no wet-lab data). + +## Can I use the results for my research? +Yes, with the understanding that all results are computational predictions. + +## Is it safe? +The pipeline is dry-lab only — no biological experiments are conducted. All code is open source (Apache 2.0). diff --git a/docs/evidence/GUIDE_ASSUMPTIONS_REGISTER.md b/docs/evidence/GUIDE_ASSUMPTIONS_REGISTER.md new file mode 100644 index 00000000..1673e7bc --- /dev/null +++ b/docs/evidence/GUIDE_ASSUMPTIONS_REGISTER.md @@ -0,0 +1,22 @@ +# Assumptions Register Guide + +How to document and track assumptions. + +## What to Record +- Assumptions about data quality +- Assumptions about model behavior +- Assumptions about benchmark validity +- Assumptions about user environment + +## Format +Each assumption should include: +- What the assumption is +- Why it's reasonable +- What would happen if it's wrong +- When it should be reviewed + +## Example +| Assumption | Basis | Risk if Wrong | Review Date | +|-----------|-------|---------------|-------------| +| AMPs are cationic | Literature consensus | Non-cationic AMPs undervalued | Next benchmark cycle | +| Swiss-Prot decoys are valid negatives | Standard practice | Benchmark AUROC inflated | Next data refresh | diff --git a/docs/evidence/GUIDE_CLAIM_WORDING_STYLE.md b/docs/evidence/GUIDE_CLAIM_WORDING_STYLE.md new file mode 100644 index 00000000..d8e809b2 --- /dev/null +++ b/docs/evidence/GUIDE_CLAIM_WORDING_STYLE.md @@ -0,0 +1,22 @@ +# Claim Wording Style Guide + +How to write about computational results without overclaiming. + +## Do Use +- "Computationally nominated candidate" +- "Predicted antimicrobial peptide" +- "Dry-lab candidate" +- "Selected by reproducible pipeline" +- "Evidence package" +- "Benchmark-supported under stated assumptions" + +## Don't Use +- "Drug candidate" — requires wet-lab evidence +- "Proven antimicrobial" — computation does not prove +- "Safe in humans" — requires clinical evidence +- "Validated by computation" — computation triages, doesn't validate +- "Breakthrough therapy" — requires clinical evidence + +## Rule of Thumb +If you wouldn't say it about a random sequence without running any tests, +you shouldn't say it about a computationally nominated candidate. diff --git a/docs/evidence/GUIDE_DATA_SOURCE_DOCS.md b/docs/evidence/GUIDE_DATA_SOURCE_DOCS.md new file mode 100644 index 00000000..7bdcddbe --- /dev/null +++ b/docs/evidence/GUIDE_DATA_SOURCE_DOCS.md @@ -0,0 +1,24 @@ +# Data Source Documentation Guide + +Every dataset used by the pipeline must be documented. + +## Required Information +- Source URL or reference +- License information +- Download date +- Version or release +- Description of the data +- Known biases or limitations + +## Format +Use a dataset card in `data/README.md` or in the relevant evidence document. + +## Example +```markdown +## Dataset: Known AMPs (500) +- Source: UniProt reviewed + APD6 natural +- License: CC BY 4.0 (UniProt), academic use (APD6) +- Downloaded: 2026-07-01 +- Description: 500 antimicrobial peptide sequences, 10-30 AA +- Known bias: Enriched for helical AMPs; fewer proline-rich and cysteine-rich +``` diff --git a/docs/evidence/GUIDE_NO_HYPE_WRITING.md b/docs/evidence/GUIDE_NO_HYPE_WRITING.md new file mode 100644 index 00000000..baf6f7bf --- /dev/null +++ b/docs/evidence/GUIDE_NO_HYPE_WRITING.md @@ -0,0 +1,11 @@ +# No-Hype Writing Rules + +Rules for keeping documentation honest and grounded. + +1. **No superlatives without evidence.** Don't say "best" or "first" unless you can prove it. +2. **No claims about biology without wet-lab data.** Computational results are predictions, not proof. +3. **State limitations as prominently as findings.** Every claim should be paired with its caveat. +4. **Use the weakest accurate claim.** If "suggests" is accurate, don't use "demonstrates." +5. **No future capability as current fact.** "Will be able to" is speculation, not documentation. +6. **No hidden negatives.** Failed experiments, benchmark weaknesses, and model limitations must be documented. +7. **Review before publishing.** Run `check_claims.py` on all public-facing text. diff --git a/docs/evidence/GUIDE_UNCERTAINTY_LANGUAGE.md b/docs/evidence/GUIDE_UNCERTAINTY_LANGUAGE.md new file mode 100644 index 00000000..a7542eaf --- /dev/null +++ b/docs/evidence/GUIDE_UNCERTAINTY_LANGUAGE.md @@ -0,0 +1,17 @@ +# Uncertainty Language Guide + +How to communicate uncertainty in documentation. + +## Strength of Language +| Certainty | Language | When to Use | +|-----------|----------|-------------| +| High | "The pipeline scores candidates based on..." | Documented, verifiable behavior | +| Medium | "Candidates with high ensemble scores tend to be..." | Benchmark-supported pattern | +| Low | "This suggests that..." | Single experiment or weak signal | +| Speculative | "It is possible that..." | No evidence yet | + +## Rules +- Match the language to the evidence level. +- Avoid false precision ("the candidate is 87.3% likely to be antimicrobial"). +- State uncertainty alongside every prediction. +- When uncertain, say "we don't know" — it's better than false confidence. diff --git a/docs/evidence/POLICY_CITATION_SOURCE.md b/docs/evidence/POLICY_CITATION_SOURCE.md new file mode 100644 index 00000000..090b8c32 --- /dev/null +++ b/docs/evidence/POLICY_CITATION_SOURCE.md @@ -0,0 +1,18 @@ +# Citation and Source Policy + +How to cite sources in documentation. + +## Required Citations +- All dataset sources (with license information) +- All algorithms or methods not original to this project +- All benchmark references +- All literature claims not supported by project evidence + +## Citation Format +Use inline links for web resources and footnotes for academic references. + +## Source Requirements +- Sources must be publicly accessible where possible. +- Paywalled sources should be noted as such. +- Sources must be specific (page number, section, or timestamp). +- "Personal communication" is not an acceptable citation. diff --git a/docs/evidence/POLICY_RETENTION.md b/docs/evidence/POLICY_RETENTION.md new file mode 100644 index 00000000..974c22e8 --- /dev/null +++ b/docs/evidence/POLICY_RETENTION.md @@ -0,0 +1,18 @@ +# Retention Policy Explanation + +How long documents and artifacts are retained. + +## Retention Periods +| Type | Retention | Notes | +|------|-----------|-------| +| Evidence certificates | Permanent | Historical record | +| Decision logs | Permanent | Governance record | +| Benchmark results | Permanent | Scientific record | +| Policy docs | Permanent | Until superseded | +| Run manifests | 2 years | Reproducibility | +| Temporary outputs | 90 days | Outputs/ directory | +| Discussion comments | 1 year | After issue closes | + +## Disposal +After the retention period, documents are archived. Archived documents +are never deleted without a decision log entry explaining why. diff --git a/tests/test_faq_writing_batch.py b/tests/test_faq_writing_batch.py new file mode 100644 index 00000000..11c51151 --- /dev/null +++ b/tests/test_faq_writing_batch.py @@ -0,0 +1,20 @@ +"""Tests for FAQ and writing guides batch.""" +from pathlib import Path + +FILES = [ + "POLICY_RETENTION.md", + "GUIDE_CLAIM_WORDING_STYLE.md", + "POLICY_CITATION_SOURCE.md", + "GUIDE_ASSUMPTIONS_REGISTER.md", + "GUIDE_UNCERTAINTY_LANGUAGE.md", + "GUIDE_NO_HYPE_WRITING.md", + "FAQ_PUBLIC.md", + "FAQ_MAINTAINER.md", + "FAQ_CONTRIBUTOR.md", + "GUIDE_DATA_SOURCE_DOCS.md", +] + + +def test_all_exist(): + for f in FILES: + assert Path("docs/evidence", f).exists(), f"Missing: {f}"