How I Use ChatGPT for TSDs, ERDs, and Database Documentation

Introduction

Technical documentation is one of the most useful parts of backend work, but it is also one of the easiest things to delay.

When a feature touches APIs, database tables, integrations, validation rules, and rollout steps, the code is only one part of the work. The team also needs a shared explanation of what will change, why it will change, and what risks should be reviewed before implementation.

Lately, I have been using ChatGPT more often as a documentation assistant for this kind of work. The workflow is not only asking for a draft. I use it together with Google Drive to create or modify Google Docs, convert database DDL into DBML, generate ERDs in dbdiagram.io, and create database table descriptions that can be inserted back into the Technical Specification Document.

The important boundary is this: ChatGPT helps me draft, organize, and format the documentation. It does not become the final technical authority.

I still review the design, relationships, indexes, assumptions, security impact, and rollout plan manually. That is where engineering judgment still matters.

Why Technical Documentation Still Matters

A Technical Specification Document is not paperwork. At least, it should not be.

For backend work, a useful TSD gives reviewers enough context to understand the proposed change before the code exists. It also gives future maintainers a record of why certain decisions were made. When a feature reaches production and someone has to debug it months later, a clear TSD can save hours of guesswork.

Good documentation helps answer questions like:

• What problem are we solving?
• Which APIs are affected?
• Which tables are added or changed?
• What relationships exist between the tables?
• Which edge cases should QA test?
• What happens if migration or rollout fails?
• Which assumptions are still unconfirmed?

This fits the same mindset I try to keep when building calm backend systems: reduce surprises, make behavior easier to reason about, and leave enough context for the next engineer.

The goal is not to create a long document for the sake of a long document. The goal is to create a useful shared model of the change.

What I Mean by a TSD

In my workflow, a TSD is a practical engineering document. It does not need to be fancy, but it should be complete enough for review.

Here is the structure I usually expect.

This structure gives the document a predictable shape. Reviewers know where to look. Developers know what still needs to be clarified. QA can extract scenarios from edge cases and API behavior.

My ChatGPT and Google Drive Workflow

The workflow usually starts with rough context.

I provide ChatGPT with the feature goal, affected system, current behavior, proposed change, database impact, API impact, and known risks. Then I ask it to create a TSD in Google Docs.

The Google Drive connection reduces copy-paste work. Instead of generating a long document in chat, copying it into Google Docs, and fixing the formatting manually, I can ask ChatGPT to create or modify the document directly.

This is close to the way I think about an AI-assisted engineering workflow: use AI to reduce friction, but keep the engineer responsible for the final result.

A starting prompt can look like this:

Create a Technical Specification Document for [feature name].
 
Context:
- Product:
- Feature goal:
- Current system behavior:
- Proposed change:
- APIs affected:
- Database impact:
- External dependencies:
- Risks:
- Open questions:
 
Create the document in Google Docs with these sections:
1. Background
2. Goals
3. Non-goals
4. Current Flow
5. Proposed Solution
6. API Contract
7. Database Changes
8. ERD
9. Edge Cases
10. Rollout Plan
11. Open Questions
 
Keep the tone technical, concise, and useful for backend reviewers.

The first draft is rarely final. It gives me a structured starting point. After that, I review and update the parts that need stronger technical detail.

Updating Only One Section

One thing I try to avoid is asking ChatGPT to rewrite the entire document every time something changes.

Full rewrites can introduce unnecessary wording changes, remove context that was already reviewed, or make the document harder to compare between versions. Targeted edits are safer.

For example, if the database design changes, I might use a prompt like this:

Update only the "Database Changes" section in the existing Google Docs TSD.
 
Do not rewrite other sections.
Do not change the document title.
Do not remove existing open questions.
 
Add:
- new table purpose
- column documentation
- migration notes
- index rationale
- assumptions that still need review
 
Use concise backend engineering language.

This keeps the document stable while still letting the TSD evolve as the design becomes clearer.

Converting DDL to DBML

For database-heavy features, the next step is usually the DDL.

DDL is implementation-friendly. It tells us the tables, columns, constraints, indexes, and data types. But DDL is not always the easiest format for reviewers, especially when they need to understand relationships across multiple tables.

That is where DBML helps. DBML is readable, text-based, and easy to paste into dbdiagram.io. It also gives me a diagram without manually drawing every table and relationship.

The prompt I use is strict because database documentation should not invent details:

Convert this SQL DDL into DBML for dbdiagram.io.
 
Rules:
- Preserve table names and column names exactly.
- Detect primary keys and foreign keys from constraints.
- Include indexes if present in the DDL.
- If relationships are inferred from column names, mark them as inferred.
- Do not invent tables.
- Do not invent columns.
- Return DBML only.
 
DDL:
[paste ddl here]

Here is a small DDL example:

CREATE TABLE document_requests (
  id BIGINT PRIMARY KEY,
  request_number VARCHAR(50) NOT NULL UNIQUE,
  requester_id BIGINT NOT NULL,
  status VARCHAR(30) NOT NULL,
  submitted_at TIMESTAMP NULL,
  created_at TIMESTAMP NOT NULL,
  updated_at TIMESTAMP NOT NULL
);
 
CREATE TABLE document_request_approvals (
  id BIGINT PRIMARY KEY,
  document_request_id BIGINT NOT NULL,
  approver_id BIGINT NOT NULL,
  approval_status VARCHAR(30) NOT NULL,
  approved_at TIMESTAMP NULL,
  notes VARCHAR(500) NULL,
  created_at TIMESTAMP NOT NULL,
  CONSTRAINT fk_approval_request
    FOREIGN KEY (document_request_id)
    REFERENCES document_requests(id)
);
 
CREATE INDEX idx_document_requests_status
  ON document_requests(status);
 
CREATE INDEX idx_document_request_approvals_request
  ON document_request_approvals(document_request_id);

The DBML output should preserve the table and column names:

Table document_requests {
  id bigint [pk]
  request_number varchar(50) [not null, unique]
  requester_id bigint [not null, note: "Inferred relationship, verify manually"]
  status varchar(30) [not null]
  submitted_at timestamp
  created_at timestamp [not null]
  updated_at timestamp [not null]
 
  indexes {
    status [name: "idx_document_requests_status"]
  }
}
 
Table document_request_approvals {
  id bigint [pk]
  document_request_id bigint [not null]
  approver_id bigint [not null, note: "Inferred relationship, verify manually"]
  approval_status varchar(30) [not null]
  approved_at timestamp
  notes varchar(500)
  created_at timestamp [not null]
 
  indexes {
    document_request_id [name: "idx_document_request_approvals_request"]
  }
}
 
Ref: document_request_approvals.document_request_id > document_requests.id

Notice the difference between explicit and inferred relationships.

The relationship between document_request_approvals.document_request_id and document_requests.id is explicit because the DDL contains a foreign key constraint. But requester_id and approver_id may point to a user table that is not included in this DDL. That should be marked as inferred or left as an assumption.

Generating ERDs with dbdiagram.io

After I have the DBML, I paste it into dbdiagram.io and generate the ERD.

The workflow is simple:

1. Paste the generated DBML into dbdiagram.io.
2. Let dbdiagram.io render the diagram.
3. Review the table relationships.
4. Adjust layout if needed.
5. Export the diagram image.
6. Attach the ERD to the Google Docs TSD.

The ERD is helpful because reviewers can see the relationship model quickly. A diagram is especially useful when the feature adds join tables, approval flows, history tables, or status tracking tables.

But I do not treat the generated ERD as final truth.

Generated diagrams are documentation aids. The source of truth is still the database design, the DDL, and the reviewed implementation. If the DDL changes, the DBML and ERD should be updated too.

Creating Table Descriptions from DDL

An ERD is useful, but it does not explain everything.

Reviewers often need to know what each table is for and what each column means. That is why I also ask ChatGPT to create table descriptions from the same DDL and insert them into the Google Docs TSD.

The table description usually includes:

• table purpose
• column name
• data type
• nullable
• key or index
• description
• example
• notes

The prompt should be careful about assumptions:

Create database table descriptions from this DDL and insert them into the Google Docs TSD.
 
Rules:
- Create one section per table.
- Add a short purpose for each table.
- Create a column documentation table with:
  - Column
  - Type
  - Nullable
  - Key / Index
  - Description
  - Example
  - Notes
- Preserve column names exactly.
- Do not invent business meaning.
- If a column meaning is inferred, mark it as "Assumption".
- Keep descriptions concise and useful for backend reviewers.
 
DDL:
[paste ddl here]

A table description can look like this:

This is the kind of documentation that helps reviewers understand more than the structure. It captures intent.

Full Workflow: Requirement to TSD

The full workflow looks like this:

1. Gather rough feature context from requirements, tickets, discussion notes, or existing behavior.
2. Ask ChatGPT to create a TSD in Google Docs.
3. Review the TSD manually and fix missing context.
4. Update specific sections instead of rewriting the entire document.
5. Provide the database DDL.
6. Ask ChatGPT to convert the DDL into DBML.
7. Paste the DBML into dbdiagram.io.
8. Generate and review the ERD.
9. Export the ERD image.
10. Attach the ERD to the Google Docs TSD.
11. Ask ChatGPT to create database table descriptions from the DDL.
12. Insert the table descriptions into the TSD.
13. Review relationships, assumptions, indexes, examples, and business meaning manually.

The result is a more complete technical document without spending too much time on repetitive formatting.

Review Checklist

Before I consider the TSD ready for review, I check the main sections.

TSD Review

• Is the background clear?
• Are goals and non-goals separated?
• Does the proposed solution match the actual system constraints?
• Are API contracts complete enough?
• Are edge cases realistic?
• Is the rollout plan safe?
• Are open questions visible?

ERD Review

• Are all tables included?
• Are table names preserved exactly?
• Are primary keys correct?
• Are explicit foreign keys correct?
• Are inferred relationships labeled clearly?
• Are indexes represented when they matter?
• Is the diagram readable enough for review?

Table Description Review

• Are all columns included?
• Are data types correct?
• Is nullable information correct?
• Are key and index notes correct?
• Are descriptions concise?
• Are assumptions marked clearly?
• Are example values fake but realistic?

Best Practices

The best results come from giving ChatGPT enough context.

Short prompts usually create generic documents. Specific prompts create useful drafts.

For backend documentation, I try to include:

• current behavior
• proposed behavior
• affected APIs
• affected tables
• constraints
• assumptions
• rollout risk
• edge cases

I also preserve exact names. Table names, column names, enum values, API paths, and request fields should not be rewritten casually.

This matters in the same way production API behavior matters. A TSD that changes names accidentally can create confusion during implementation and review. It is similar to why Spring Boot production error handling needs consistency: small inconsistencies become expensive when more people depend on the output.

For Java services, I also compare the documentation against implementation readiness. The checklist mindset in my Java and Spring Boot production checklist applies here too: validate assumptions, review operational behavior, and do not skip edge cases.

The DDL should remain the source of truth for database structure. DBML, ERDs, and table descriptions are derived documentation. If the DDL changes, the derived artifacts should be updated.

Common Mistakes

The most common mistake is using a vague prompt.

For example:

Create a TSD for approval feature.

That prompt does not provide enough context. It will likely produce a generic document.

A better prompt includes the current flow, proposed flow, affected tables, APIs, constraints, and known questions.

Another mistake is trusting inferred relationships too much. If the DDL does not contain a foreign key constraint, ChatGPT may still infer relationships from names like user_id, approval_id, or request_id. That can be useful, but it should be marked clearly.

Other mistakes include:

• copying DBML without checking it
• making table descriptions too verbose
• forgetting indexes
• forgetting nullable behavior
• sharing sensitive data
• omitting rollout and rollback details
• rewriting the entire document too often

The goal is not to create perfect documentation in one prompt. The goal is to create a strong draft and review it carefully.

Security Considerations

When using ChatGPT with Google Drive and technical documents, security matters.

I avoid pasting:

• secrets
• tokens
• credentials
• production customer data
• private financial records
• sensitive incident details
• internal URLs that should not be shared

If I need example values, I use fake but realistic data.

For example, REQ-2026-0001 is safer than a real production request number. A fake user ID like 501 is safer than customer data from production.

Google Drive permissions also matter. If ChatGPT creates or modifies a Google Doc, the document should still follow the team's normal access rules. Sensitive documents should not be shared broadly just because they were easier to generate.

Every company has different policy around AI tools. Follow the policy first.

Performance Considerations

Database documentation should include performance details when the feature depends on data access patterns.

For example:

• expected table growth
• read and write frequency
• indexes needed for query patterns
• pagination strategy
• archival strategy
• batch processing impact
• high-read or high-write tables
• reporting queries

If a table is expected to grow quickly, the TSD should mention how the service will query it. If an endpoint filters by status and created_at, the index discussion should not be an afterthought.

Performance notes do not need to be long, but they should be visible.

Keeping Documentation Maintainable

The hard part is not creating the first version of documentation. The hard part is keeping it aligned with implementation.

I try to keep these artifacts connected:

• TSD
• DDL
• DBML
• ERD
• table descriptions
• rollout notes

If one changes, the others may need updates.

When useful, DBML can be stored in the repository or documentation folder. That makes it easier to review changes over time instead of only keeping an exported image.

For this blog, I use a similar idea with content structure. The way I organize articles in Next.js and MDX blog architecture reminds me that text-based artifacts are easier to maintain when they can be versioned, reviewed, and improved gradually.

Good documentation is not a one-time artifact. It is a living companion to the system.

FAQ

Can ChatGPT create a complete TSD automatically?

It can create a strong first draft, but I would not treat it as complete automatically. The engineer still needs to review architecture, API behavior, database impact, edge cases, security concerns, and rollout risk.

Is DBML better than manually drawing ERDs?

For many backend workflows, yes. DBML is text-based, easier to version, and quick to render in dbdiagram.io. Manual diagrams are still useful for high-level architecture, but DBML is convenient for database structure.

Can ChatGPT infer relationships from DDL?

It can infer relationships from column names, but inferred relationships should be marked clearly. If the DDL does not contain a foreign key constraint, the relationship should be reviewed manually.

Should table descriptions be generated from DDL?

Yes, as a starting point. The generated table descriptions should still be reviewed, especially for business meaning, status values, financial fields, nullable behavior, and assumptions.

Is it safe to connect ChatGPT to Google Drive?

It can be useful, but it depends on policy, permissions, and data sensitivity. Do not include secrets, credentials, production customer data, or sensitive internal details unless your organization allows it.

What should engineers review manually?

Engineers should review system design, API contracts, database relationships, indexes, assumptions, security concerns, performance implications, rollout plans, and any generated descriptions that explain business meaning.

Conclusion

Using ChatGPT for TSDs, ERDs, DBML, and database documentation is useful because it removes repetitive drafting and formatting work.

The value is not replacing engineering judgment. The value is getting a structured document faster, then spending more time on the parts that matter: design correctness, assumptions, risks, and operational safety.

For me, the best workflow keeps ChatGPT as an assistant. It can create the TSD draft, modify Google Docs, convert DDL to DBML, help generate ERDs, and prepare table descriptions. But the engineer still owns the final review.

That balance is what makes the workflow practical.

FAQ Schema

{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "Can ChatGPT create a complete TSD automatically?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "ChatGPT can create a strong first draft, but engineers still need to review architecture, API behavior, database impact, edge cases, security concerns, and rollout risk."
      }
    },
    {
      "@type": "Question",
      "name": "Is DBML better than manually drawing ERDs?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "For many backend workflows, DBML is easier to version and render with tools like dbdiagram.io. Manual diagrams are still useful for high-level architecture."
      }
    },
    {
      "@type": "Question",
      "name": "Can ChatGPT infer relationships from DDL?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "ChatGPT can infer relationships from column names, but inferred relationships should be marked clearly and reviewed manually if no foreign key constraint exists."
      }
    },
    {
      "@type": "Question",
      "name": "Should table descriptions be generated from DDL?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Generated table descriptions are useful as a starting point, but engineers should review business meaning, nullable behavior, indexes, status values, and assumptions."
      }
    },
    {
      "@type": "Question",
      "name": "Is it safe to connect ChatGPT to Google Drive?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "It can be useful if permissions and company policy allow it. Avoid sharing secrets, credentials, production customer data, or sensitive internal details."
      }
    },
    {
      "@type": "Question",
      "name": "What should engineers review manually?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Engineers should manually review design correctness, API contracts, relationships, indexes, assumptions, security concerns, performance impact, and rollout plans."
      }
    }
  ]
}