From 127e1d9613289037ff37f322d8ca772cb316d7e5 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 28 Mar 2026 07:29:53 +0000 Subject: [PATCH 1/3] Initial plan From f9dfeb9c6b7f7195089807e6b16e2f3dceab8b65 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 28 Mar 2026 07:33:01 +0000 Subject: [PATCH 2/3] docs: add prioritized new-user documentation gaps to roadmap Agent-Logs-Url: https://github.com/SkBlaz/py3plex/sessions/367d7c9f-44a7-439d-9e69-78f3f11658b5 Co-authored-by: SkBlaz <10035780+SkBlaz@users.noreply.github.com> --- docfiles/project/roadmap.rst | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/docfiles/project/roadmap.rst b/docfiles/project/roadmap.rst index bb648552..f9be6a89 100644 --- a/docfiles/project/roadmap.rst +++ b/docfiles/project/roadmap.rst @@ -111,6 +111,39 @@ The following features have been requested by the community. For the full list a * Enhanced performance for centrality computations - **Planned** * Integration with popular graph databases - **Under consideration** +Documentation Gaps Blocking New-User Adoption +--------------------------------------------- + +After reviewing ``README.md``, ``AGENTS.md``, and the current docs tree, these are the highest-impact documentation gaps for first-time users: + +1. **Conflicting example inventory and scale claims** + + * README says **170+** examples. + * ``AGENTS.md`` says **267** examples. + * ``docfiles/getting_started/tutorial_10min.rst`` says **26 focused examples** in its section list. + + New users cannot quickly trust which navigation map is current. + +2. **Broken or stale example path references in onboarding docs** + + Several onboarding pages reference example folders that are not present in the current top-level ``examples/`` layout (for example ``examples/00_quickstart/`` and category folders such as ``communities/`` and ``temporal/``). This blocks copy-paste adoption because the first command often fails with "file not found". + +3. **No single canonical "start here" path across README and docs** + + README, docs homepage, and tutorial pages each present different starting flows. The project has strong content depth, but first-time users lack one authoritative linear path from install -> first successful query -> next steps. + +4. **README flagship snippet is advanced before a minimal validated success case** + + The first large code sample is feature-rich (community detection + UQ + grouping + explainability), which is valuable for power users but can overwhelm new adopters who need a shortest possible "first success" script first. + +5. **Audience boundary between AGENTS.md and human docs is unclear** + + ``AGENTS.md`` is comprehensive and agent-oriented, but there is no prominent warning in beginner-facing docs clarifying that it is an expert/automation playbook rather than the recommended first learning resource for humans. + +6. **No documented single source of truth for doc metadata drift-prone fields** + + Counts and path catalogs (examples totals, folder maps, quickstart file paths) are repeated in multiple places without a clearly designated canonical source, causing recurring drift. + Vote on Features ~~~~~~~~~~~~~~~~ From 1e8347e2b73efc1fde941e4f269cb15660c473cb Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 28 Mar 2026 07:33:46 +0000 Subject: [PATCH 3/3] docs: make documentation-gap findings actionable with source refs Agent-Logs-Url: https://github.com/SkBlaz/py3plex/sessions/367d7c9f-44a7-439d-9e69-78f3f11658b5 Co-authored-by: SkBlaz <10035780+SkBlaz@users.noreply.github.com> --- docfiles/project/roadmap.rst | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/docfiles/project/roadmap.rst b/docfiles/project/roadmap.rst index f9be6a89..ebd14fed 100644 --- a/docfiles/project/roadmap.rst +++ b/docfiles/project/roadmap.rst @@ -118,15 +118,20 @@ After reviewing ``README.md``, ``AGENTS.md``, and the current docs tree, these a 1. **Conflicting example inventory and scale claims** - * README says **170+** examples. - * ``AGENTS.md`` says **267** examples. - * ``docfiles/getting_started/tutorial_10min.rst`` says **26 focused examples** in its section list. + * README says **170+** examples *(as observed on 2026-03-28 in ``README.md``)*. + * ``AGENTS.md`` says **267** examples *(as observed on 2026-03-28 in ``AGENTS.md``)*. + * ``docfiles/getting_started/tutorial_10min.rst`` says **26 focused examples** *(as observed on 2026-03-28 in that file's "Next Steps" section)*. New users cannot quickly trust which navigation map is current. 2. **Broken or stale example path references in onboarding docs** - Several onboarding pages reference example folders that are not present in the current top-level ``examples/`` layout (for example ``examples/00_quickstart/`` and category folders such as ``communities/`` and ``temporal/``). This blocks copy-paste adoption because the first command often fails with "file not found". + Several onboarding pages reference example folders that are not present in the current top-level ``examples/`` layout. For example: + + * ``docfiles/getting_started/tutorial_10min.rst`` references ``examples/00_quickstart/...`` and category folders such as ``examples/communities/`` and ``examples/temporal/``. + * ``docfiles/examples/index.rst`` describes a folder taxonomy that includes categories not present in the current top-level examples tree. + + This blocks copy-paste adoption because the first command often fails with "file not found". 3. **No single canonical "start here" path across README and docs**