|
1 | | -# Project Documentation Structure |
2 | | - |
3 | | -This document outlines a recommended structure for comprehensive project documentation. While tailored for a Go-based CLI tool like `subenum`, the principles are broadly applicable. |
4 | | - |
5 | | -## 1. Core Documentation (`README.md`) |
6 | | - |
7 | | -This is the gateway to your project. It should be concise, informative, and guide users to other relevant documentation. |
8 | | - |
9 | | -* **Project Title & Tagline:** Clear and descriptive. |
10 | | -* **Badges (Optional but Recommended):** |
11 | | - * Build status (e.g., GitHub Actions) |
12 | | - * Code coverage |
13 | | - * Go Report Card |
14 | | - * License |
15 | | - * Version/Release |
16 | | -* **Brief Description:** What the project does in a few sentences. |
17 | | -* **Cybersecurity Context / Educational Goals (If applicable):** Why this tool/project is important, especially from a learning or security perspective. |
18 | | -* **Features:** Bulleted list of key capabilities. |
19 | | -* **Prerequisites:** What users need to have installed/configured. |
20 | | -* **Installation / Setup:** |
21 | | - * From source (e.g., `go build`, `go install`) |
22 | | - * Pre-compiled binaries (if provided) |
23 | | - * Docker (if applicable) |
24 | | -* **Usage:** |
25 | | - * Basic command-line syntax. |
26 | | - * Explanation of all flags and arguments. |
27 | | - * Clear examples of common use cases. |
28 | | -* **Output Explanation:** Describe what the output means. |
29 | | -* **Contributing:** Guidelines for developers who want to contribute (link to `CONTRIBUTING.md`). |
30 | | -* **License:** Link to `LICENSE.md`. |
31 | | -* **Contact / Support (Optional):** How to get help or report issues. |
32 | | - |
33 | | -## 2. Architecture Documentation (`ARCHITECTURE.md` or `/docs/architecture.md`) |
34 | | - |
35 | | -This describes the "how" of your project. It's crucial for maintainers and contributors. |
36 | | - |
37 | | -* **Overview:** High-level diagram and explanation of the system's components and their interactions. |
38 | | -* **Key Components / Modules:** |
39 | | - * For each major component (e.g., in `subenum`: argument parsing, wordlist processing, DNS resolution, concurrency management, output formatting): |
40 | | - * Purpose and responsibilities. |
41 | | - * Key functions/structs. |
42 | | - * Interactions with other components. |
43 | | -* **Data Flow:** How data moves through the system (e.g., from wordlist to DNS resolver to output). |
44 | | -* **Concurrency Model (If applicable):** |
45 | | - * Explanation of how concurrency is achieved (e.g., goroutines, channels, worker pools). |
46 | | - * Rationale for design choices. |
47 | | - * Potential bottlenecks or considerations. |
48 | | -* **Error Handling Strategy:** How errors are propagated, logged, and handled. |
49 | | -* **External Dependencies:** List of external libraries and why they were chosen. |
50 | | -* **Design Decisions & Rationale:** Important architectural choices made and the reasons behind them. This can include alternatives considered and why they were not chosen. |
51 | | -* **Future Considerations / Potential Improvements:** Areas for future development or refactoring. |
52 | | - |
53 | | -## 3. Developer Guide (`DEVELOPER_GUIDE.md` or `/docs/developer_guide.md`) |
54 | | - |
55 | | -Information for those who want to build, test, or contribute to the project. |
56 | | - |
57 | | -* **Getting Started:** |
58 | | - * Cloning the repository. |
59 | | - * Setting up the development environment (Go version, tools, environment variables). |
60 | | - * Building the project from source. |
61 | | -* **Running Tests:** |
62 | | - * How to execute unit tests, integration tests, etc. |
63 | | - * Test coverage tools. |
64 | | -* **Coding Style / Conventions:** Link to any style guides or linters used. |
65 | | -* **Debugging Tips:** Common issues and how to troubleshoot them. |
66 | | -* **Making Changes:** |
67 | | - * Branching strategy. |
68 | | - * Commit message conventions. |
69 | | - * Pull Request process. |
70 | | -* **Dependencies Management:** How to add or update dependencies (e.g., `go get`, `go mod tidy`). |
71 | | - |
72 | | -## 4. Contribution Guidelines (`CONTRIBUTING.md`) |
73 | | - |
74 | | -How others can contribute to the project. |
75 | | - |
76 | | -* **Code of Conduct:** Link to `CODE_OF_CONDUCT.md`. |
77 | | -* **How to Contribute:** |
78 | | - * Reporting bugs (issue tracker, templates). |
79 | | - * Suggesting enhancements. |
80 | | - * Submitting pull requests. |
81 | | -* **What to Work On:** (Optional) Links to "good first issues" or a project board. |
82 | | - |
83 | | -## 5. Code of Conduct (`CODE_OF_CONDUCT.md`) |
84 | | - |
85 | | -Sets expectations for community interaction. Adopt a standard one like the Contributor Covenant. |
86 | | - |
87 | | -## 6. License (`LICENSE` or `LICENSE.md`) |
88 | | - |
89 | | -Specifies how the software can be used, modified, and distributed (e.g., MIT, Apache 2.0, GPL). |
90 | | - |
91 | | -## 7. Changelog (`CHANGELOG.md`) |
92 | | - |
93 | | -A chronological list of notable changes for each version/release. |
94 | | - |
95 | | -* Follows Keep a Changelog format (Added, Changed, Deprecated, Removed, Fixed, Security). |
96 | | - |
97 | | -## 8. Examples (`/examples` directory) |
98 | | - |
99 | | -* Provide more extensive or varied examples of how to use the tool. |
100 | | -* Sample wordlists, configuration files, or scripts. |
101 | | - |
102 | | -## 9. API Documentation (If applicable - for libraries or tools with an API) |
103 | | - |
104 | | -* For Go projects, this is often generated using `godoc`. |
105 | | -* Ensure public functions and types are well-commented. |
106 | | - |
107 | | -## 10. `/docs` Directory (Optional - for larger projects) |
108 | | - |
109 | | -For more complex projects, you might move `ARCHITECTURE.md`, `DEVELOPER_GUIDE.md`, and other detailed documents into a dedicated `/docs` directory to keep the root directory cleaner. |
110 | | - |
111 | | ---- |
112 | | - |
113 | | -This structure provides a solid foundation. Adapt it to the specific needs and complexity of your project. |
| 1 | +# Documentation map |
| 2 | + |
| 3 | +Where each piece of subenum's documentation lives and who it is for. The files under `docs/` are also the [project site](https://tmhsdigital.github.io/subenum/); this page is left out of the site build. |
| 4 | + |
| 5 | +## For users |
| 6 | + |
| 7 | +| Document | What it covers | |
| 8 | +|---|---| |
| 9 | +| [`README.md`](../README.md) | What subenum is, install, quick start, every flag, output formats, the TUI, completions and the man page | |
| 10 | +| [`docs/start.md`](start.md) | First scan, the run-quality verdict, what to read next | |
| 11 | +| [`docs/cli.md`](cli.md) | CLI reference: flags (generated from the code into [`_includes/flags.md`](_includes/flags.md)), exit codes, config file and `SUBENUM_*` defaults | |
| 12 | +| [`docs/pipelines.md`](pipelines.md) | Chaining with dnsx, httpx and nuclei; JSON logs; takeover candidates first | |
| 13 | +| [`docs/monitoring.md`](monitoring.md) | Scheduled scans with `-diff`, the GitHub Action ([`action.yml`](../action.yml)) and SARIF alerts | |
| 14 | +| [`docs/docker.md`](docker.md) | The container image: volumes, output files, permissions | |
| 15 | +| [`docs/labs.md`](labs.md) | Offline exercises against [`examples/labs/`](../examples/labs/) zones with `-simulate-zone` | |
| 16 | +| [`docs/library.md`](library.md) | The Go library `pkg/subenum`; the full API reference is on pkg.go.dev | |
| 17 | +| [`examples/advanced_usage.md`](../examples/advanced_usage.md) | Longer recipes: wildcards, record types, rate limiting, the reliability guard, CSV | |
| 18 | +| [`tools/README.md`](../tools/README.md) | The `wordlist-gen` tool | |
| 19 | + |
| 20 | +## For contributors |
| 21 | + |
| 22 | +| Document | What it covers | |
| 23 | +|---|---| |
| 24 | +| [`docs/CONTRIBUTING.md`](CONTRIBUTING.md) | Setup, tests, lint, pull requests | |
| 25 | +| [`docs/DEVELOPER_GUIDE.md`](DEVELOPER_GUIDE.md) | Project tree, hermetic testing, previewing the site, extension points | |
| 26 | +| [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) | How the engine works: packages, resolution, dispatch, output, error handling | |
| 27 | +| [`docs/ROADMAP.md`](ROADMAP.md) | Where the project is heading and known constraints | |
| 28 | +| [`docs/CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) | Community expectations | |
| 29 | + |
| 30 | +## Project files |
| 31 | + |
| 32 | +| File | What it covers | |
| 33 | +|---|---| |
| 34 | +| [`CHANGELOG.md`](../CHANGELOG.md) | Changes per release (Keep a Changelog); each release's notes come from its section | |
| 35 | +| [`SECURITY.md`](../SECURITY.md) | Supported versions and how to report a vulnerability | |
| 36 | +| [`LICENSE`](../LICENSE) | GPL-3.0 | |
| 37 | +| [`CITATION.cff`](../CITATION.cff) | How to cite subenum | |
| 38 | + |
| 39 | +## Keeping docs current |
| 40 | + |
| 41 | +- Regenerate the site's flag table with `make docs-flags`; `go test .` fails when it or the README flag table drifts from the CLI. |
| 42 | +- List anything on `main` but not yet released in [`_data/unreleased.yml`](_data/unreleased.yml) so the site tags it, and empty the lists in the release commit. |
0 commit comments