Tuesday, January 31, 2006

Software Distribution Making

An important process in software development is the making of the distribution.
Here are some good practices:

  • Make sure tarballs always unpack into a single new directory (not the current directory!).
  • Include a README with:
  1. A brief description of the project.
  2. A pointer to the project website (if it has one).
  3. Notes on the developer's build environment and potential portability problems.
  4. A roadmap describing important files and subdirectories.
  5. Either build/installation instructions or a pointer to a file containing same (usually INSTALL).
  6. Either a maintainers/credits list or a pointer to a file containing same (usually CREDITS).
  7. Either recent project news or a pointer to a file containing same (usually NEWS).
  8. Project mailing list addresses.
  • Respect and follow standard file-naming practices
  • README: The roadmap file, to be read first.
  • INSTALL: Configuration, build, and installation instructions.
  • AUTHORS: List of project contributors (GNU convention).
  • NEWS: Recent project news.
  • HISTORY: Project history.
  • CHANGES: Log of significant changes between revisions.
  • COPYING: Project license terms (GNU convention).
  • LICENSE: Project license terms.
  • FAQ: Plain-text Frequently-Asked-Questions document for the project.
  • filenames with all-caps names are human-readable metainformation about the package
  • Design for upgradability. use version-numbered directories
  • Under linux, provide RPMs
  • Provide checksums.
These tips come from Eric's Raymond excellent book "The Art of Unix Programming".
Read also my other posts on this book:
- Basics of the Unix Philosophy
- Good Development Practices for Open-Source Developers
- Design Rules for Textual Data Formats

Digg this story

Friday, January 20, 2006

Best Practices for Writing Use Cases

Are your use cases clear both for your users and for your developers ? Here are some tips:
  • Be careful with UML diagrams. Only use them for a high level model to show relationships between actors and use cases. Use case descriptions are textual
  • Main scenario 3-9 steps. Bird's eye view
  • No IF-statements, but main scenario's plus extensions
  • Brainstorm on goal failures
    • evaluate, eliminate, merge
  • Manage your energy: work breadth first
    • Actors and goals
    • Use case brief, main scenario
    • Failure conditions
    • Failure handling
  • Goal based, find the right goal. 3 levels: summary, user goals, subfunctions
  • What does the primary actor really want ?
  • WHY is this actor doing this step/goal ?
  • Write short, clear, easy to read use cases
    • Use cases are communication instruments
    • Customers/Users: Is it this what you want ?
    • Developers: Can you develop this ?
    • Like "Actors verbs the system", ie. Customer debets his account
  • Use Cases describe the functional requirements of a system, other requirements are described in supplementary specifications: performance, user interface requirements, IO formats, data formats, ...
With which of these tips can you improve your use cases ? Or do you have other tips ?

To learn more about writing use cases: Writing Effective Use Cases, by Alistair Cockburn, Addison-Wesley 2001.

Digg this story