Chapter 3: Design and discovery

Introduction

This introduction explains why planning matters in software design and how ChatGPT can help establish a foundation for an application.

• Value of upfront design: Explain why taking time to plan an application's architecture matters, even when programmers are tempted to rush design.
  Why it matters: The value of planning explains why the project begins with design rather than code.
• ChatGPT as design collaborator: Describe how collaborating with ChatGPT can help during the design phase without treating its output as a finished application.
  Why it matters: It frames AI as a way to strengthen early design thinking, not as a substitute for continued development.

Key terms: design phase, architecture, maintenance costs, ChatGPT, targeted questions

3.1 Getting to know ChatGPT

Introduces ChatGPT’s strengths and limitations and explains why developers should prompt thoughtfully and evaluate its responses.

• ChatGPT’s developer-facing strengths: Describe ChatGPT as an OpenAI large language model trained on varied texts that can help developers generate text and code, develop ideas, and be creative.
  Why it matters: These strengths explain why ChatGPT can help during software design, not just coding.
• Limits of ChatGPT responses: Explain why convincing ChatGPT responses still need human verification, including its best-guess generation and its lack of independent validation or genuine understanding.
  Why it matters: A persuasive answer is not evidence that the answer is correct or suitable for the situation.
• Thoughtful prompting and evaluation: State the section’s practical approach to using ChatGPT effectively: craft thoughtful prompts and evaluate its responses, including when using it for software design and documentation.
  Why it matters: Prompting guides the assistance you get, while evaluation keeps you responsible for what you use.

Key terms: ChatGPT, large language model (LLM), text generation, stochastically, best guess, verify the output, real-world context, thoughtful prompts, evaluating responses, design and documentation

3.2 The problem

The section defines the HAM radio practice-test problem and shows why developers should clarify requirements and probe design questions before coding.

• Problem First Design Focus: Explain why the developer should ask what problem the application solves before opening an IDE, and keep returning to that question during development.
  Why it matters: Starting with the problem gives design choices a purpose.
• Practice Test Application Requirements: Describe the user need and the initial requirements for the HAM radio practice-test application, including how a practice session selects questions and why it is web-based.
  Why it matters: These requirements connect the proposed features to the learner’s need to practice and find areas to study.
• Design Questions Before Coding: Explain why the initial requirements are not yet a reason to start coding, and describe how focused ChatGPT questions could expose overlooked design considerations.
  Why it matters: Exploring unanswered questions early can prevent the first implementation from overlooking important needs.

Key terms: problem, HAM radio license, practice tests, pool of questions, 35-question sessions, web application, design process, blind spots, alternative solutions, edge cases

3.3 Creating the right prompt

This section shows how to structure a prompt for a software design document and briefly introduces several other prompting approaches.

• Role prompts and response style: Explain that a role prompt asks ChatGPT to act in a specified role and is intended to shape the style of its response.
  Why it matters: A role gives the AI a useful perspective for a design task.
• Design prompt components: Describe how the example prompt combines a role, task, context, instructions, and desired output form to request a software design document, and explain when adding these components is useful.
  Why it matters: These components make a design request more specific without imposing a rigid template.
• Other basic prompting approaches: Distinguish the brief examples of chain-of-thought, few-shot, and more specific persona prompting given in this section.
  Why it matters: These examples offer other ways to frame a request when a basic role prompt is not enough.

Key terms: role prompt, persona prompt, Introduction, Task, Contextual information, Instructions, Closing, software design document, Chain of thought prompting, Few-shot prompting

3.4 Measuring the effect on the design process

The section explains why using ChatGPT for a first design-document draft can save time while leaving refinement and judgment to developers.

• Creation to curation shift: Explain how a ChatGPT-generated first draft changes design documentation work from writing on a blank page to refining a draft that retains the team's intent.
  Why it matters: The time saving comes from reducing initial drafting, not from skipping review.
• Design process time savings: Describe the section's claimed time savings and their limits: document generation saves time, and the author reports up to 70% less time in design meetings without reduced documentation quality, while results may vary.
  Why it matters: The claimed benefit is time freed for more interesting work, even after allowing for revisions.

Key terms: first draft, refinement, creation to curation, net gain, design meetings, documentation quality

3.5 A design document created with ChatGPT

This section uses the software development life cycle to frame a lightweight ChatGPT design document, shows how a prompt and conversation context shape it, and identifies risks to check in AI-generated designs.

• SDLC stages and purpose: Explain how the software development life cycle structures work from planning through maintenance and why considering its stages helps guide a design document.
  Why it matters: The stages give you a way to spot missing considerations without treating the design as a rigid checklist.
• Lightweight design document prompt: Describe why the author asks ChatGPT for a single, abstract software design document and what the example prompt supplies to make it useful.
  Why it matters: A focused request can produce a useful starting design without demanding more documentation than the project needs.
• Conversation context for refinement: Explain why the author keeps refining the document within a single ChatGPT conversation.
  Why it matters: Keeping the conversation together helps later requests build on what you have already told ChatGPT.
• AI design document red flags: Describe the kinds of shortcomings the author says to watch for in an AI-generated design document.
  Why it matters: These checks help keep a plausible-looking design grounded in the application's real needs.

Key terms: software development life cycle (SDLC), planning, analysis, design, implementation, testing, software design document, prompt, structure, potential pitfalls

3.6 Software design document: HAM radio license practice test application

The section presents ChatGPT’s design document for a HAM radio practice-test app and evaluates its components, risks, and technology choices.

• Practice Test System Components: Describe the application’s purpose and how its four proposed components support a practice test.
  Why it matters: The component breakdown turns a short app description into parts you can design and discuss.
• Design Details And Pitfalls: Explain the concrete question, selection, interface, and grading details the document adds, including the pitfalls it flags.
  Why it matters: These details reveal practical questions that a high-level component list alone would miss.
• Technical Stack Evaluation: Explain why the author does not simply accept ChatGPT’s proposed technologies for this small application.
  Why it matters: An AI-generated design is a proposal to evaluate against the project, not a stack to adopt unchanged.
• Future Feature Restraint: Explain the author’s qualified response to ChatGPT’s proposed future features.
  Why it matters: It distinguishes useful design ideas from commitments to build features now.

Key terms: question pool database, question selector, user interface, grading component, question_id, question_text, options, correct_option, pitfalls, technical stack

3.7 Digging deeper

This section explains why clarifying key details in the initial design document can reduce changes during development.

• Upfront design clarity: Explain why the author wants to decide key details before building from the design document.
  Why it matters: Settling important design choices early can make the document a steadier guide during development.

Key terms: document, excessive churn, key details upfront

3.7.1 System overview (section 2)

The section uses ChatGPT to expand a brief system overview for a HAM radio practice-test app, then explains why the expanded design still needs human review.

• Practice test component flow: Trace how the proposed question pool database, question selector, user interface, and grading component work together to deliver a practice test and its results.
  Why it matters: This flow gives you a way to discuss the proposed application before implementing it.
• Targeted overview expansion: Explain why the author asks ChatGPT to elaborate on a specified section of the design document rather than accepting the brief overview as written.
  Why it matters: A focused follow-up can make a design document more useful for its intended readers.
• Human review of AI drafts: Justify why the expanded ChatGPT overview should be treated as a source of ideas and drafting help, not as an automatically accurate design document.
  Why it matters: A convincing-looking draft can help you think without becoming an unchecked source of design decisions.

Key terms: Question Pool Database, Question Selector, User Interface, Grading Component, System Overview, key subjects, same chat instance, inaccuracies, review and double-check, implied accuracy

3.7.2 Technical stack (section 5)

The section shows how chat context can shape a technical-stack draft and why developers should revise the AI’s suggestions for their application.

• Contextual technical stack prompting: Explain how the author steers ChatGPT toward a Python web application by adding Flask to the existing chat context, then asks for more detail with a short follow-up prompt.
  Why it matters: You can refine a design discussion without restating every instruction in each prompt.
• Reviewing proposed stack choices: Explain why the generated technical stack is a useful draft rather than a final decision, using the React.js suggestion and the author’s choice of Flask HTML templates as an example.
  Why it matters: A plausible AI suggestion still needs to fit the complexity and needs of the application you are building.

Key terms: chat context, Flask, Technical stack, tech stack, React.js, HTML templates

3.8 Generating user stories for our project

This section explains why the author asks ChatGPT to act as a product owner and how an existing chat context lets the request for user stories stay brief.

• Product owner task organization: Explain that product owners manage a project's backlog and try to order tasks to fit the project's flow, a job ChatGPT can help with.
  Why it matters: It explains the project-organizing purpose behind the request for user stories.
• Contextual product owner prompt: Describe how the author requests user stories: keep the existing project chat, ask ChatGPT to act as an experienced product owner, and make a short, clear request without repeating project background.
  Why it matters: It shows how an existing chat context supports a concise request for a different kind of project document.

Key terms: product owner, backlog of tasks, user stories, context (chat), experienced product owner, prompt

3.8.1 Defining roles in prompts

This section explains how assigning ChatGPT a role shapes its responses and helps developers explore a problem from different perspectives.

• Role-based output framing: Explain how naming a role in a prompt gives ChatGPT a persona that shapes the style and substance of its response, such as technical details from a software designer or user needs from a product owner.
  Why it matters: Choosing a role helps you get a response suited to the kind of discussion you want to have.
• Purposeful role selection: Justify choosing a role suited to the question, and describe how trying different roles can reduce irrelevant output and reveal overlooked angles.
  Why it matters: A well-chosen role can focus the conversation, while another role may surface concerns you missed.

Key terms: role, persona, context, roles, steer the output, different angles

3.8.2 The output: User stories document

This section presents ChatGPT’s unedited user stories for the HAM radio practice-test application and notes that the stories can change during development.

• User-centered application stories: Describe how the generated stories express what different users want from the application and why, covering the test experience as well as needs such as progress tracking and support.
  Why it matters: The stories turn the application idea into concrete expectations from a user’s point of view.
• Changing user story set: Explain why the generated list of user stories need not remain fixed as the project develops.
  Why it matters: Treating the list as revisable leaves room for needs discovered during development.

Key terms: user stories, primary interactions, expectations, user feedback, project requirements

3.8.3 Analyzing the output

This section explains why ChatGPT-generated user stories need human review and how to assess an initial draft at a high level.

• Human review of AI drafts: Explain why ChatGPT’s initial user stories should be reviewed rather than accepted as-is: AI can quickly produce a useful framework, but the reader must check and understand the output before using it.
  Why it matters: Review lets you benefit from ChatGPT’s speed without treating its draft as automatically accurate.
• High-level user story checks: Describe the high-level questions to ask of the draft user stories: whether they follow the user’s journey logically, seem accurate, and use language that fits the intended documentation.
  Why it matters: These checks help turn a generic draft into documentation suited to the project.

Key terms: due diligence, initial draft, frameworks and outlines, user stories, logical progression, user’s journey

3.8.4 User stories document in detail

The section reviews ChatGPT-generated user stories for a practice-test application, identifying useful requirements while showing where the author would revise or defer them.

• Practice Test User Journey: Describe how the user stories follow a test taker from account setup through taking a test, receiving a grade, and tracking progress. Give examples of features suggested along that journey.
  Why it matters: Following the user journey helps turn broad stories into features the application may need.
• User Story Fit and Priority: Explain how the author evaluates the generated stories against the application's needs, keeping useful requirements while identifying thin, vague, or potentially later features.
  Why it matters: Reviewing each suggestion keeps the project plan useful without treating every generated idea as an immediate commitment.
• Human Ownership of AI Documentation: Explain why the author treats the generated document as a guide rather than a fixed design, including the need to reword language that does not express the author's inclusive intent.
  Why it matters: Keeping ownership of the document lets you preserve useful AI suggestions while making the design fit your users and project.

Key terms: user journey, user stories, Taking the Test, Submitting and Grading, Tracking Progress, backlog, MVP, User Interface and Experience, Accessing the Test, generative AI

3.9 Summary