Communicating the work: reports, presentations and professional ethics

Engineers are judged on what others understand of their work. A capstone that solved a real problem but cannot explain it, in a report the client can read, a presentation a panel can follow and a reflection that shows what the team learned, earns less than it deserves. This lesson covers the written and spoken deliverables at the end of the term, and the professional obligations that come with building software for other people: ethics, honesty about results and, in Canada, the rules about who may call themselves an engineer. CMPUT-401 covered communicating with clients and CMPUT-421 covered presenting user research; here we put them together for the final weeks.

Writing for your readers

Every document has readers with different needs. The client wants to know what the product does, whether it worked and what to do next, in plain language. The supervisor wants evidence of process, decisions and learning. A future maintainer wants to know how the system is built and why. Write for the least technical reader who must understand each part, and put technical detail where technical readers will look for it. The most common failure in capstone reports is writing everything at the same level of jargon, so that the client gives up on page two and the maintainer finds no real detail anywhere.

Plain writing is a skill, not a talent. Put the main point first, in every section and every paragraph. Use short sentences and concrete words: 'drivers get a text the day before' rather than 'the system disseminates notification payloads'. Prefer active voice, so readers know who did what. Use numbers with context, such as 'missed pickups fell from about 8 in 100 to about 4 in 100 during the pilot', rather than 'a significant improvement'. Define terms the first time you use them. Then cut: most first drafts are a third longer than they need to be. A quick readability score is a crude but useful prompt to rewrite.

# A rough readability check for report sections aimed at the client.
# Flesch reading ease = 206.835 - 1.015 (words/sentences) - 84.6 (syllables/words).
# Higher is easier; 60-70 is plain English. Syllables are estimated, so treat it as a hint.
import re
def syllables(word):
    w = word.lower().strip(".,;:!?()'\"")
    if not w: return 0
    groups = re.findall(r"[aeiouy]+", w)
    n = len(groups)
    if w.endswith("e") and n > 1 and not w.endswith(("le", "ee")): n -= 1
    return max(1, n)
def flesch(text):
    sentences = max(1, len(re.findall(r"[.!?]+(\s|$)", text)))
    words = re.findall(r"[A-Za-z']+", text)
    syl = sum(syllables(w) for w in words)
    return 206.835 - 1.015 * len(words) / sentences - 84.6 * syl / len(words), len(words) / sentences
drafts = {
    "summary, first draft": ("The implementation leverages an asynchronous task-processing architecture "
        "to facilitate the dissemination of configurable notification payloads to heterogeneous "
        "volunteer populations, thereby optimizing operational throughput and minimizing attrition."),
    "summary, rewritten": ("RescueRoute reminds drivers about their shifts by email or text. "
        "If a driver does not confirm, Grace sees it the day before. "
        "During the pilot, missed pickups fell from about 8 in 100 to about 4 in 100."),
}
for name, text in drafts.items():
    score, wps = flesch(text)
    print(f"{name:22} reading ease {score:6.1f}, {wps:4.1f} words per sentence")

summary, first draft   reading ease  -77.5, 27.0 words per sentence
summary, rewritten     reading ease   73.4, 11.3 words per sentence

The final report

The final report is the permanent record of the project. Team Relay's ran to about 25 pages plus appendices, following the outline their course required. It began with a one-page executive summary written for the co-op's board. It then covered the problem and discovery evidence; the solution and its main features with screenshots; the architecture with the C4 diagrams and a summary of ADRs; the process, including sprint history, velocity and what the team changed at retrospectives; quality and testing evidence; privacy and responsible design decisions; pilot results against the success metrics; the handover; and limitations and future work. Appendices held the full ADRs, the test strategy, the data inventory and the runbook.

Report results honestly. A capstone pilot is small and short, and the evidence it produces is limited. Say so. Team Relay reported that missed pickups among 30 pilot drivers fell from about 8 per cent to about 4 per cent over four weeks, that this was encouraging but based on a small sample with no control group, that the coordinator time target was missed and why, and that the SLO was narrowly missed with a clear explanation. Reviewers trust a report that presents its weaknesses; they distrust one where every metric happens to have hit its target. Never adjust, select or round numbers to look better than they are.

Use figures and tables to carry evidence. A screenshot of the coordinator dashboard explains it better than a page of description. A chart of missed pickups by week, baseline against pilot, shows the result at a glance. Every figure needs a caption that says what it shows and why it matters, and alternative text if the report will be published as a web page, as CMPUT-421 taught. Cite sources for any claim that is not your own, including standards, statistics and the libraries and tools that the product depends on.

Presenting and demonstrating

The final presentation is usually 15 to 20 minutes to a panel of instructors, the client and sometimes guests from industry, followed by questions. Its job is to show a working product solving a real problem, and to show that the team understands what it built and why. Lead with the problem and the people it affects, not the technology. Spend at least a third of the time on a live demonstration of real user journeys on real data shapes. Then show results, how it is built and handed over, and what you learned. End on time. Everyone on the team should speak, and each person should know the whole project well enough to answer questions about any part.

# Planning a 15-minute final demonstration: allocate time, then check it fits.
plan = [
    ("Problem and who it affects (Priya)",              1.5),
    ("What we built: one-sentence summary",             0.5),
    ("Live demo: driver claims, gets reminder, confirms (Sofia)", 3.0),
    ("Live demo: coordinator dashboard and report (Marcus)",      2.5),
    ("Results from the pilot, including what missed (Lin)",       2.0),
    ("How it is built and handed over (Ethan)",          2.0),
    ("What we learned and what is next",                 1.0),
    ("Buffer for things going wrong",                    2.5),
]
limit = 15.0
t = 0.0
for part, minutes in plan:
    print(f"{t:5.1f}-{t + minutes:5.1f}  {part}")
    t += minutes
print(f"total {t} of {limit} minutes" + ("" if t <= limit else "  OVER: cut something"))
speakers = sum(1 for p, _ in plan if "(" in p)
print(f"named speakers: {speakers}; demo share of time: {100 * (3.0 + 2.5) / limit:.0f}%")

  0.0-  1.5  Problem and who it affects (Priya)
  1.5-  2.0  What we built: one-sentence summary
  2.0-  5.0  Live demo: driver claims, gets reminder, confirms (Sofia)
  5.0-  7.5  Live demo: coordinator dashboard and report (Marcus)
  7.5-  9.5  Results from the pilot, including what missed (Lin)
  9.5- 11.5  How it is built and handed over (Ethan)
 11.5- 12.5  What we learned and what is next
 12.5- 15.0  Buffer for things going wrong
total 15.0 of 15.0 minutes
named speakers: 5; demo share of time: 37%

Live demonstrations fail at the worst moment, so plan for it. Demonstrate on the staging environment with a prepared data set, not on production with real volunteers' details. Rehearse the full demo at least twice on the presentation machine and network. Have a recorded video of the same journeys ready to play if the live system or the network fails, and say so calmly if you switch to it. Use large text, zoom in on what matters, and narrate what the user is trying to do rather than which button you are clicking. Team Relay's demo began with a phone screen mirrored to the projector showing a driver receiving a reminder, which made the problem real for the panel in ten seconds.

Prepare for questions. List the twenty questions the panel is most likely to ask, and agree who answers which kind. Typical questions: Why this architecture? What would you do differently? How do you know it works? What happens when the client's volunteer developer leaves? What did each of you contribute? If you do not know an answer, say so and say how you would find out. Do not argue with the panel; if they raise a real weakness, acknowledge it and explain what you would do about it with more time.

Posters, videos and portfolios

Many programs end with a showcase where teams present posters or short videos to visitors. A poster is not a report on a wall: it should be readable from two metres away, with a title that states the problem, one large image of the product, three or four key results and almost no paragraphs. A two-minute video should show the product in use, with captions so it works without sound. Both are good portfolio pieces. With the client's permission, a public project page with screenshots, a short write-up and a link to the open-source repository is one of the most useful things a graduating student can show an employer.

Reflective writing

Most capstone courses ask each student for an individual reflection. Reflection is not a diary of what happened; it is analysis of what you learned and how you will act differently. A useful structure is: describe a specific situation, analyse why it went as it did using ideas from your courses, and state what you would do next time. 'Our sprint 2 burndown stayed flat for five days because the reminder story was blocked on a consent question; next time I would raise blockers at the stand-up on the first day rather than waiting for the client meeting' is reflection. 'Sprint 2 was challenging but we learned a lot' is not. Be honest about your own mistakes; supervisors value self-awareness far more than polish.

Professional ethics

Software affects people who never see its code. The ACM Code of Ethics and Professional Conduct, last revised in 2018, sets out principles every computing professional should know: contribute to society and human well-being, avoid harm, be honest and trustworthy, be fair and take action not to discriminate, respect privacy, honour confidentiality, and maintain high standards of professional competence. The capstone is often the first time these principles meet a real situation. Team Relay met them several times: in choosing not to build a no-show prediction model that might have treated volunteers unfairly, in minimizing personal data, in reporting a missed SLO honestly, and in refusing to promise the client features they could not deliver in the time available.

Ethical problems in capstones are usually small and practical. A teammate wants to copy a large chunk of code from an online answer without checking its licence. The client asks the team to add a feature that would track volunteers' locations continuously 'just in case'. A deadline tempts someone to disable a failing test rather than fix it. Pressure to show success tempts someone to choose the week with the best numbers for the report. In each case the principles point the same way: be honest, respect licences and privacy, avoid harm, and raise concerns with the team, the supervisor or the client rather than quietly going along. Raising a concern is a professional skill, and the supervisor is there to help you practise it.

Who may call themselves an engineer

In Canada, 'engineer' is a protected title. Each province and territory regulates the practice of engineering and the use of titles such as 'professional engineer', 'P.Eng.' and, in most provinces, 'engineer' itself, through a regulator such as Professional Engineers Ontario or Engineers and Geoscientists BC; Engineers Canada coordinates the regulators nationally. Regulators have long held that job titles such as 'software engineer' imply engineering licensure, and some have sent cease-and-desist letters to technology companies over job postings. Alberta changed its law in late 2023: the Engineering and Geoscience Professions Amendment Act (Bill 7) allows non-licensed people to use the title 'software engineer' there, while 'professional engineer' and 'P.Eng.' remain restricted, a change other regulators opposed. In other provinces the restriction still applies. A computing science graduate can work as a software developer anywhere, and in Canada the safe practice is to use 'software developer' unless you are licensed or work in Alberta. Licensure as a P.Eng. generally requires an accredited engineering degree or equivalent assessment, supervised experience and an ethics and law exam; check your province's rules, which change.

Whatever the title, the obligations are similar. Software increasingly controls things that can hurt people: vehicles, medical devices, power systems, financial decisions and, at a smaller scale, whether a shelter receives food today. Competence, honesty about limits and willingness to say no to unsafe or unethical work are professional duties whether or not a licence is involved. Many graduates go on to roles where they review others' work, approve releases or design systems used by thousands of people; the habits of documenting decisions, testing honestly and raising concerns early, practised in the capstone, are the ones those roles need.

Worked examples