Skip to content

readme.md

Latest commit

 

History

History
77 lines (75 loc) · 3.47 KB

readme.md

File metadata and controls

77 lines (75 loc) · 3.47 KB
Raw

Hello Product

Recommendations I try to follow for all products I build, regardless of framework. Presented in alphabetical order:

  • Accessibility
    • Full assessment every 90 days
      • Accessibility Insights assessment
    • All features thoroughly tested
      • One finger
      • Mouse-only
      • Keyboard-only
      • Eyes closed + screen reader
      • Sound disabled
    • See also usability
  • Documentation
    • Markdown documents for everything
    • Ideally everything is in one docs folder except for readme.md
    • Comment liberally: it's easier to remove than it is to add later
  • Generative artificial intelligence (GenAI)
    • Never creative
      • AI-generated images/video/audio is only used for demo/explanatory purposes
      • AI-generated text is never copy-pasted, always rewritten by me
        • Generally I only use GenAI with writing to correct typos
    • Always optional
      • Users should be able to easily navigate the site without using GenAI tools
      • See also usability
    • Always disclosed
      • Prominent "AI-generated content may be incorrect" or similar disclaimer near every message
    • Never tries to "be a person"
      • Never refers to itself as "I" or "we", instead says things like "this bot" or "this product"
      • Not open to general conversation, always focused on purpose-built tasks
    • Never trusted
      • All AI output is checked by handwritten procedures, e.g., making sure all links exist
      • Comprehensive e2e tests are in place and pass before any GenAI changes are deployed
    • Ethically trained
      • StarCoder LLM
  • Performance
    • Test all pages with "Slow 3G" connection
    • Defer all images, but with Cumulative Layout Shift handled
    • Use low-res images first with optional high-res images based on connection speed, connection type?, user preferences
    • Prioritize sending minified content instead of sending inspectable content
      • Source code linked anyway, see "transparency" section
    • Only apply CSS rules where necessary (e.g. don't apply rules to all figure elements if only some need them)
    • Use stylesheets instead of repeated style attributes
  • Privacy
    • No cookie banner: Only use strictly necessary cookies
    • Transparent tracking: If I do track info, it's always
      • Opt-in
      • Easy to opt out (max 4 clicks: menu > settings > telemetry > opt out)
      • Clear what data is being sent (sample JSON payload)
      • Clear what data will never be sent (IP, location, etc.)
      • Clear when the tracked data changes
        • Users are automatically opted out?
        • Subtle badge appears in settings submenu
        • Notification? (max 1 change per month if so? Notification spam sucks)
  • Project management
    • Use the lightest tools that work
    • Use automation whenever reasonable
      • Re-evaluate bot configs on a regular basis
    • Infrastructure as code (e.g. GitHub REST API for new repos)
  • Security
    • I only build static sites right now, so no special concerns here
  • Testing
    • Automated tests for as much as possible
    • If automated tests are infeasible:
      • Detailed manual repro steps are available (GitHub Gist or commit)
      • Issue is opened for automating tests for that area
  • Transparency
    • Source code linked to each project
    • Licensed under MIT or other widely-recognized FOSS license
  • Tooling
    • When working with source code, spell-checker should be enabled
  • Usability
    • Command palette should be available for all interactions with the site
      • All settings discoverable
      • All pages discoverable
      • Actions like "sign out", "sign in"