docs: family umbrella for Azure Portal screenshots strategy

Closed
  • Is something wrong?
#492 4 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
25/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Stale
Tech stack
azure, python
Domain
documentation

Research direction

This is a family-level tracking issue; the remaining implementation is tracked in azure-functions-db-python#151, while the durable-graph child issue was cancelled because that project was retired. Read the standards here and compare the reference screenshots in azure-functions-logging-python/docs/assets and their use in docs/deployment.md. Done for this umbrella means the database child issue is completed and merged, followed by a post-rollout review.

Written by the indexing model from the issue text.

Description

chore documentation priority: low size: XS

Context

Current priority: priority:low. The maintainer's 2026-10-03 decision keeps only db #151 as deferred screenshot work. Durable Graph is retired and has no active rollout task.

Across the Azure Functions DX Toolkit family (6 sibling repos), only azure-functions-logging-python currently includes Azure Portal screenshots in user-facing docs (4 shots in docs/assets/). After a strategic Oracle consultation, we decided on a selective rollout (NOT family-wide) because:

  • Pre-1.0 API stability + Portal UI churn make blanket maintenance unjustified
  • Portal isn't the right proof surface for every library (e.g., CLI-first tools, scaffolders, request validators)
  • The logging 4-shot before/after template is the gold-standard reference for value-demonstration but not a mandatory template

This umbrella tracks the family-level decision and child issues.

Family decision matrix
Repo Priority Status Reason
azure-functions-logging-python Reference Done (4 Portal shots) Gold-standard example; no change needed
azure-functions-durable-graph-python Retired Cancelled — yeongseon/azure-functions-durable-graph-python#53 Retired on 2026-10-02; excluded from the remaining rollout
azure-functions-db-python MEDIUM yeongseon/azure-functions-db-python#151 Portal helps verify deploy + resource wiring
azure-functions-validation-python LOW Deferred Request/response examples > Portal UI
azure-functions-scaffold-python LOW Deferred Scaffolding precedes Portal; no narrative fit
azure-functions-doctor-python SKIP Excluded CLI-first; existing GIF/terminal assets sufficient
Standards (apply to all child issues)
  • Per-repo copies: each repo owns its docs/assets/portal/*.png (no shared submodule)
  • Custom narratives: 1-3 shots per repo, tailored to its value proposition (not a mandatory 4-shot template)
  • Insertion priority: docs/getting-started.md > docs/examples/*.md > docs/deployment.md > README
  • Internationalization: same English-UI shots reused across all 4 locales (en/ko/ja/zh-CN); no per-locale screenshots
  • Format: PNG, total added assets <1 MB per repo
  • No new MkDocs plugins (no glightbox/gallery — Material default rendering only)
  • Redaction: no secrets, subscription IDs, tenant names, connection strings, or personal data visible
  • Tone: screenshots are orientation/proof, NOT click-by-click instructions (mitigates Portal UI drift)

Acceptance Checklist

  • Child issue filed in azure-functions-durable-graph-python (HIGH priority) — cancelled: project retired — yeongseon/azure-functions-durable-graph-python#53
  • Child issue filed in azure-functions-db-python (MEDIUM priority) — yeongseon/azure-functions-db-python#151
  • Remaining child (db #151) completed and merged
  • Post-rollout review: did Portal shots measurably help onboarding? If NO → STOP, do not expand to deferred repos

Out of scope

  • azure-functions-validation-python — deferred until concrete onboarding gap appears
  • azure-functions-scaffold-python — deferred (scaffolding precedes Portal)
  • azure-functions-doctor-python — explicitly skipped (CLI-first; existing assets sufficient)
  • Family-wide screenshot bundle/submodule (per-repo copies chosen)
  • New MkDocs plugins (glightbox, gallery, lightbox)
  • Localized (per-locale) screenshot variants

References

Dominant language
Python
Stars
15
Forks
0
Avg merge
7h 53m
Merged PRs (30d)
90

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from yeongseon/azure-functions-logging-python

All issues in yeongseon/azure-functions-logging-python

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.