awslabs / awslabs/aidlc-workflows

[Docs]: Add autogenerated onboarding index files (recommended reading order)

Open
#463 0 comments 0 reactions 0 assignees View on GitHub
documentation
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.