Practical developer guide
What to know
Document a web development project by connecting its purpose and constraints to implemented decisions and reproducible evidence. Include working test paths, accurate credits, dated performance and accessibility methods, and clear limitations. A concise evidence pack is more useful than unsupported promotional claims.
A strong website does not always explain itself. A reviewer can see the interface, browse several pages and attempt the main user journey, yet still miss a great deal of thoughtful engineering: the accessibility work that made an interaction usable, the content architecture that keeps a large archive manageable, or the resilience that allows a checkout to recover when a service fails.
That does not mean a submission needs a long promotional presentation. It means the essential evidence should be findable, accurate and easy to check. Good technical documentation connects a problem to an implemented decision and, where possible, to a result that can be reproduced.
This guide is for teams preparing a website for a technical review, design award entry, client handover or engineering portfolio. It describes good evidence-gathering practice, not a claim that every awards programme demands a particular document or scoring format. Web Dev Awards' public judging criteria provide useful context: technical execution, performance, accessible interaction and creative development all deserve consideration beyond screenshots.
Begin with the product, not the technology stack
A list of frameworks rarely explains why a website is good. Saying a project uses React, Next.js, Astro, WordPress or a headless CMS is factual background, not proof of engineering quality. Tools are choices; what matters is whether those choices serve the experience.
Start with four short answers:
- What was the website built to do? Identify its primary audience and main task. An architecture portfolio may need to make project work understandable. A ticketing site needs a reliable booking path.
- What made the task difficult? Describe a real constraint: thousands of archived records, poor connectivity, localisation, editorial updates, complex product options or support for older devices.
- What changed in the final implementation? Explain the actual technical decision. Name a technology only where it helps the reader understand the trade-off.
- How was the decision checked? Show a test, observable behaviour or reliable measurement, including any limitations.
An answer can be concise. For example: “The search catalogue contained thousands of historic entries. We introduced server-side pagination and stable canonical URLs so visitors could browse each page directly and search engines could follow the archive without relying on an infinite-scroll interaction.” That is much more useful than “Built with cutting-edge technology for outstanding performance.”
Prepare a working demonstration
A reviewer should be able to use the submitted website without a special account, undocumented setup or broken promotional link, unless the project's legitimate purpose requires restricted access. If access is necessary, document the safe review method and any limitations. Do not share real customer credentials or private data.
Check these basics before submitting:
- Main navigation and key links work on desktop and mobile.
- Important actions have clear outcomes and usable error messages.
- Fonts, images, videos and third-party assets do not leave large empty areas when they fail.
- A reviewer can distinguish the original site from a modern redesign or archived screenshot.
- Forms can be assessed safely without sending unintended real orders or messages.
For older work, preserving a dated screenshot and an accurate description of its historical context may be more appropriate than implying the original website is still online. Explain whether the accessible URL is the original project, a reconstruction or an archive.
Document technical decisions with evidence
A useful decision note is not a code dump. It should make the reasoning transparent.
| Question | Example of useful evidence |
|---|---|
| What problem did the team see? | Reproduced mobile filtering delay on a defined device |
| What options were considered? | Client-only sorting versus server-backed filtering |
| Why was one option selected? | Needed shareable filter URLs and a small client bundle |
| What was implemented? | Server-filtered query with bounded pagination |
| How was it checked? | Repeatable browser tests and response data |
| What remains imperfect? | Search suggestions still depend on an external service |
If you're describing a conversion improvement, include the exact measurement method and period. A 12% increase in orders after a redesign does not automatically mean the redesign caused it. Advertising, seasonality, pricing and other changes may explain part of the movement. Correlation should be described as correlation unless the study can support causal attribution.
Demonstrate performance without cherry-picking
A single Lighthouse score is a useful diagnostic snapshot, but not a full account of how visitors experience the site. A website can perform well in one lab run and behave poorly for users on slower devices, or it can contain an interaction problem that the initial load test misses.
For load performance, the current Core Web Vitals focus on Largest Contentful Paint (LCP), Interaction to Next Paint (INP) and Cumulative Layout Shift (CLS). Google's recommended “good” thresholds, evaluated at the 75th percentile of page loads, are LCP of 2.5 seconds or less, INP of 200 milliseconds or less, and CLS of 0.1 or less. These are user-experience thresholds, not proof that a project is technically excellent overall.
If you publish measurements, include:
- The URL or page type, test date, browser and device profile.
- Whether results come from real users (field data) or a simulated/laboratory run.
- The time window and sample size where available.
- Mobile and desktop separately where the audience justifies it.
- Which interactions were tested, not just how the first page loaded.
- A short explanation of what was changed and what was not controlled.
Prefer an honest “No public field data was available, so this review uses a repeatable laboratory method” to fabricated precision. For complex applications, a short screen recording of the problem and a trace of the expensive task can provide better diagnostic evidence than an uncontextualised score badge.
For a worked example of an interaction investigation, see the Web Dev Awards technical series on engineering better INP and cross-check the methodology with the official documentation. Link to the relevant internal Web Dev Awards article only once its actual public URL is confirmed.
Show accessible interaction in action
Accessibility claims need to survive use, not just a colour-contrast report. Demonstrate a complete task using the keyboard: reach navigation, open and close a menu, find the main content, complete a form and recover from an error.
For interactive components, document focus behaviour, accessible names, keyboard operation and any screen-reader announcements. If a modal opens, focus should be managed appropriately and returned to the trigger when it closes, subject to the user's workflow. If a form rejects a value, the error needs to be identifiable and associated with the relevant field.
A good audit note might say: “At the time of testing, the mobile filter could be opened using the keyboard and its focus order matched the visual order. The filter's selected values were announced through the control's accessible state. We tested with a specific browser and screen reader combination; that does not establish universal compatibility.”
Avoid blanket claims such as “100% accessible” or “WCAG certified” unless there is an appropriately scoped audit and valid basis for the claim. Manual testing and automated checks complement one another.
Explain the creative work in implementation terms
Creative development is not simply animation. It can involve a genuinely useful interface idea, unusual but legible navigation, original interaction design, responsible motion or a technical approach that expands the design without compromising access.
Show the creative decision and its practical consequences. A particle effect may be technically sophisticated but reduce legibility on a low-end phone. A deliberately simple transition may be more effective because it preserves orientation. Reviewers need to understand what the creative choice accomplishes, whether it is consistent with the rest of the experience, and how the site behaves when motion is reduced or unavailable.
For motion-heavy work, document the prefers-reduced-motion fallback and whether essential information can still be accessed without animation. Include mobile screenshots or a short video only where they reveal something that a link to the working site would not.
Give credit accurately
Large web projects involve designers, developers, content teams, accessibility specialists, photographers and clients. An award entry is stronger when it gives credit to the right people rather than compressing all contributions into a single studio label.
Use consistent project names, working URLs and contributor roles. Distinguish the design studio from the development studio where they differ. Obtain permission before using private project material, unpublished client data, personal staff information or internal analytics. If someone from the evaluating organisation helped create the work, be transparent about the relationship and follow the applicable conflict-of-interest policy.
A public portfolio should not use invented testimonials or manufactured technical results to make the work appear more substantial. Genuine limitations, identified and handled well, are part of a credible engineering story.
Keep a compact review evidence pack
Most projects do not need a fifty-page PDF. An organised set of links and a clear summary is easier to assess:
- A one-page project summary covering purpose, audience, constraints, solution and contributors.
- The working URL, key test paths and any restricted-access explanation.
- A small selection of desktop and mobile screenshots showing distinct states, including one interactive state.
- Technical notes describing two or three important implementation decisions.
- Performance and accessibility results with dates, methodology and limitations if available.
- An accurate statement about launch date, significant redesigns and whether the current site matches the submitted version.
The best evidence reduces guesswork. It should make it possible for an independent reader to check claims instead of trusting a list of adjectives.
What not to include
Avoid slogans in place of technical detail, undocumented percentage improvements, unsupported technology claims, excessive unedited screenshots and private credentials. Do not send a full proprietary codebase where a small reproducible explanation will do. Do not present an award nomination as a win.
Most importantly, do not confuse quantity with quality. Two well-documented engineering decisions usually say more about a team's judgement than twenty feature names without context.
Final checks before sharing a project
Open the site on a phone. Complete the primary task. Navigate key elements with a keyboard. Try a representative error state. Check whether the main images and page content are accessible without running complex scripts. Verify links and credits. If you claim performance improvements, read the underlying data once more.
A technical review should reveal how a website behaves when someone actually uses it. Good project documentation makes that work observable, while leaving the reviewer free to reach an independent conclusion.
Frequently asked questions
Do I need to disclose every framework and library?
No. Name technologies that explain meaningful decisions or constraints. The quality of the implementation matters more than the length of the technology list.
Can I submit an old website that is no longer live?
That depends on the particular awards programme's eligibility rules. For a technical portfolio, preserve dated screenshots, explain the original context and avoid implying a reconstruction is the original live product.
Is a Lighthouse score enough for a performance claim?
No. It can support a repeatable laboratory investigation. Field performance, user interactions, test setup and changes over time may tell a different story.
Should I include a technical case study if there was no dramatic improvement?
Yes, if it explains a real design or engineering trade-off. Clear reasoning and accurate evidence are valuable even without an impressive percentage.
Further reading: Web Dev Awards judging · Core Web Vitals · WCAG 2.2 · Google's LCP guidance