diff --git a/DISCOVERY.md b/DISCOVERY.md new file mode 100644 index 0000000..2624276 --- /dev/null +++ b/DISCOVERY.md @@ -0,0 +1,46 @@ +# Public Project Discovery and Measurement + +Help readers solve a concrete problem before asking them to adopt a project. +Relevant descriptions and topics support discovery; rankings and engagement +still depend on usefulness, competing results, links, and actual adoption. + +## Publish an accurate project page + +1. State what the project does, its language or framework, and its intended use. +2. Show a reproducible starting example and explain expected output. +3. Link to source, tests, limitations, security reporting, and licensing terms. +4. Use relevant GitHub topics and a real workflow badge rather than a static passing badge. +5. Link related projects only where they help the reader complete the task. +6. Label demonstrations, sample metrics, and proposed architecture clearly. + +[GitHub README guidance](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes) +and [repository topics guidance](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/classifying-your-repository-with-topics) +explain these discovery surfaces. + +## Share useful evidence + +Publish a working walkthrough, a small benchmark with its dataset and method, +or a reproducible bug fix. Share it only in relevant communities that permit +project promotion, disclose affiliation, and answer technical questions. +Never buy stars, automate unsolicited promotion, or manufacture visits. + +## Measure changes over time + +Record a dated baseline before promotion, then compare consistent windows. +GitHub repository traffic exposes recent views, visitors, clones, and referrers +to users with the required access; capture it before the rolling window expires. +Keep maintainer checks separate from evidence of organic interest when possible. + +| Signal | What it can tell you | Limitation | +| ------------------------------------- | --------------------------------------------------------- | -------------------------------------------------- | +| Unique visitors and referrers | Whether people reach the project and where they come from | Does not prove successful adoption | +| Clones and forks | Whether people download or experiment | Does not prove active use | +| Stars | Whether people save or express interest | Does not measure software quality | +| Reproducible issues and contributions | Whether people engage with implementation | Counts need qualitative review | +| Search observations | Whether a specific query shows the project | Location, date, and personalization change results | + +Log query, search engine, date, location, and observed result URL when reviewing +search visibility. Use problem-specific queries, not just the repository name. +Do not report a top-three position without an observed result and its context. +[Google's SEO guidance](https://developers.google.com/search/docs/fundamentals/seo-starter-guide) +explains why indexing and first-place rankings cannot be guaranteed. diff --git a/README.md b/README.md index f57c2c5..1242109 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,16 @@ -# Engineering Standards — Acadify Solution +# Software Engineering Standards — Git, Code Review, and Releases > A versioned engineering handbook for secure software development, Git workflows, code review, software releases, and AI-assisted engineering. +## Choose a starting point + +- Set up a team workflow with [branching and Git guidance](standards/branching-git.md). +- Review a pull request with the [peer review checklist](standards/peer-reviews.md). +- Prepare a release using [release management guidance](standards/release-management.md). + +See [DISCOVERY.md](DISCOVERY.md) for a practical guide to documenting public +projects, sharing reproducible examples, and measuring discovery honestly. + ## What is this repository? **Acadify Solution Engineering Standards** is a practical, reusable software engineering handbook for teams that want consistent development practices across the software delivery lifecycle. @@ -93,12 +102,6 @@ A release process should define readiness checks, deployment verification, rollb See [Release Management](standards/release-management.md). -## Search topics - -This repository is relevant to searches and discussions about: - -**software engineering standards, engineering handbook, development standards, coding standards, secure coding practices, Git branching strategy, Git workflow, pull request standards, code review checklist, peer code review, release management, software development lifecycle, DevOps practices, engineering governance, engineering documentation, AI-assisted coding, AI engineering standards, LLM engineering, RAG development, prompt engineering, AI security, AI evaluation, production software engineering.** - ## Quality and maintenance The repository uses automated formatting and Markdown linting through GitHub Actions. Changes are reviewed through the repository contribution workflow, with ownership and security guidance documented separately.