awslabs / awslabs/aidlc-workflows
[Docs]: Add autogenerated onboarding index files (recommended reading order)
- Dominant language
- TypeScript
- Stars
- 4.6k
- Forks
- 827
- Avg merge
- 1d 21h
- Merged PRs (30d)
- 165
Description
### Version
v1 (current)
### Type of Documentation Problem
Unclear or confusing explanation
### Location
general
### Description
Currently the ai-dlc methodology generates a significant number of documentation files and automated artifacts. For people who are new to the team, or who have been away from the project for a long time, it can be difficult to know where to start and in what order to read the files to gain a clear understanding of what the project is about.
### Suggested Fix
Implement ai-dlc behavior to detect documentation folders and create a 000-index.md with a short, recommended reading order. Example:
```
## Objective
The proposed order is an **orientation guide** to help you understand what the project is about. **You are not required** to follow the full sequence—open only the files you needico.
## Index
0. **000-index.md** (this file)
1. [001-reverse-engineering-timestamp.md](001-reverse-engineering-timestamp.md)
2. [002-business-overview.md](002-business-overview.md)
3. [003-architecture.md](003-architecture.md)
4. [004-component-inventory.md](004-component-inventory.md)
5. [005-technology-stack.md](005-technology-stack.md)
6. [006-code-structure.md](006-code-structure.md)
7. [007-dependencies.md](007-dependencies.md)
8. [008-api-documentation.md](008-api-documentation.md)
9. [009-code-quality-assessment.md](009-code-quality-assessment.md)
```
```
aidlc-docs/
├── 000-index.md
├── construction/
└── inception/
├── 000-index.md
├── application-design/
├── plans/
│ └── 000-index.md
├── requirements/
├── reverse-engineering/
│ ├── 000-index.md
│ ├── 001-reverse-engineering-timestamp.md
│ ├── 002-business-overview.md
│ ├── 003-architecture.md
│ ├── 004-component-inventory.md
│ ├── 005-technology-stack.md
│ ├── 006-code-structure.md
│ ├── 007-dependencies.md
│ ├── 008-api-documentation.md
│ └── 009-code-quality-assessment.md
└── user-stories/
```
Contributor guide
Research direction
Start by locating the ai-dlc behavior that detects documentation folders and generates artifacts; the issue does not name a source file or test. Review the 000-index.md examples and folder layout, then verify that each detected documentation folder receives an index with a recommended reading order and valid links.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- documentation, tooling
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100