Houjun Liu

Documentation and Specification

See also Software Development Methodologies


  • Comments
  • Readme
  • Wiki


  • UX
  • UI
  • High-Level Architecture (libraries, external APIs)
  • Low-Level Architecture (modules, functions, internal APIs)


  • Almost anything hardcoded (constants, strings, etc.)
  • Anything confusing, tricky, nonstandard
  • Historical notes: if something is added/removed, write it down
  • TODO for bugs or hacks


  • Best used as a quick-start guide
  • What are key pieces of info they will pieces of info they will need?
    • What is your code supposed to do?
    • How does someone run your code?
    • How does a new engineer get set up?
  • General overview of how things are laid out, with links to wiki pages with details


  • In-depth explanation of subsystems and modules
  • Separate pages for each subsystem
  • Include decisions of their design decisions
  • Discussions of why systems are not designed differently

UI/UX Spec

  • How do we know what the software is supposed to do?
  • Varying levels of resolution
    • User stories
    • All the way up to granular details of UI elements

Don’t forgot to document defaults!