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

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