Skip to end of metadata
Go to start of metadata

Architecture/Methodology/Tools (AMT) Discussions

Goals and Scope

Applying Christopher Alexander's and the Gang of Four's "Design Pattern" concepts to methodology, these discussions will help our group to see the landscape of or various engagements in software design and development with common understanding and perspectives. A slide deck presented on 31 August might help to put this idea in context; it is attached to this page in PDF and PowerPoint formats.

These discussions seek to:

  • Improve how we do our work as software designers and developers by assuring we speak the same language about how we work
  • Make our work more efficient by lowering communication-impedance
  • Make it easier for members of our group to transition between projects, to the extent that we have common methods, processes, tools, and understanding about our work as service software designers and developers

Upcoming Discussions

  • October 26, 2010 - "Tools and Methods for Testing Services"
  • November 23, 2010 - "Sharing Services - The Vocabulary Problem"
  • December 7, 2010 (question) | January 2011 - "Sharing Services - The Person / Profile / AuthN / Problem"

Discussion Topics and Roadmap

Development Environment and Infrastructure for Service Development
  1. Documentation Strategy and Platform, including a collaborative venue for sharing and evolving requirements, service models, service designs, service contracts, and implementation API documentation; and including curatorial resources/effort devoted to ensure continued usability and navigability as documentation grows organically.
  2. Issue Tracker
  3. Source Control Management / Version Control

    Unknown macro: {multi-excerpt}

  4. Development, Integration, Quality Assurance, and Production layers of deployment infrastructure
  5. Automated Build Process
  6. Automated Testing (both unit-testing and continuous integration)
  7. Coding Standards (consistent naming and formatting conventions that facilitate the ability of an organization to maintain code written by a diverse group of programmers) -- noting that consistency and broad acceptance is more important than an 'objectively best' set of standards, and standards that are maintained externally to all Project Bamboo Partners is strongly preferred in order to sidestep disagreements over strongly-held opinions on fine-grained matters of coding style.
  8. API Documentation Standards (ideally generated from appropriately commented code); generated API documentation must be augmented by class and package introductions that articulate design philosophy and point to related external documentation (papers on algorithms, etc.), and, ideally, by usage examples and (as in the Flickr API) a 'playground' facility for exploring the API from the documentation site/pages.
  9. Service Versioning Standards (cf. Erl, Web Service Contract Design & Versioning for SOA; this general chapter applies to both RESTful services and those that comply with WS-* standards)
Stages of Realization - From Contract to Implementation
  1. Service modeling, design, and contract definition are successive stages of detail and commitment in defining the nature and behavior of a body of related services. The Extreme Programming technique of soliciting User Stories as drivers for "Service Stories" has been a useful technique in the CollectionSpace project for progressing through these stages of service definition (cf. CSpace's User Story Repository on the project wiki; and Service Stories in the project issue tracker).
    1. Service Modeling involves creating a comprehensive view of entities (things being modeled) and operations (things a user might want to do to an entity, such as create or delete it) in a group of related services; and, importantly, the relations between entities. The service model also sketches how services interact with (depend on) each other. These are high level definitions; for example, one might describe a "Person" as an entity in a body of services, but wouldn't worry about whether a representation of a person includes a name, a government-issued ID number, and/or a collection of social networking platforms on which the person is active. Candidate services are provisionally identified as sets of operations (capabilities) that operate on identified entities. Code re-use, contract alignment, or resource-model alignment are core values sought at this stage of service development, and are carried forward to the extent possible:
      1. To the degree possible, service modeling efforts seeks alignment with related service inventories.
      2. Service re-use - whether wrapped (e.g., for simplification) or not - is ideal; contract alignment is an interoperability win; and alignment of resource modeling is better than no alignment.
      3. In some cases, necessary and fundamentally different core assumptions will make this alignment difficult or impossible; but we hold that value in a service-oriented context is deeply tied to alignment at one of these levels.
    2. Service Design more formally describes services as candidate operations (capabilities) and candidate input/output parameters (messages), where parameters might be complex data structures whose detail is only roughly defined at this stage. Relations between entities are more concretely defined, expressed as service designs that realize the needed relationships. Relationships between services (dependencies) are described in further detail.
    3. Service Contract Definition involves formal description of operations and messages that constitute each service. Service Contracts can be expressed in a formal definition, such as WSDL or WADL; but in any case conform to an adopted standard (cf. Thomas Erl's Canonical Interface Expression design pattern). Upon release, Service Contracts are subject to a formal governance process (cf. Service Design Principal #2), which preserves alignment to the degree possible (cf. bullet #1 and its sub-bullets, above).
  2. Service Implementation is the programming effort that realizes software to fulfill the Service Contract.
    1. Implementation occurs in iterative, evolving phases, which includes alpha- and/or beta-releases that invite integration and user testing.
    2. Release candidates are subjected to validation and ratification by both technical Quality Assurance teams and groups of end-users.
  3. User Experience Design (UX) inquires how different types of users would best interact with service functionality. It surfaces scope boundaries and factors that impact prioritization by discovering needs and workflows natural to users or prospective users of a body of services.
Application and UI Development on top of Services
  1. <Include issues specific to Application design for applications that are built on top of services.>
  2. User Centered Design (UCD) methodologies are generally accepted as best practice that leads to successful User Interfaces (UIs). The Fluid Project based at the University of Toronto has developed a Design Handbook that describes tools and techniques to conduct UCD (such as the Fluid Design and Development Process). Project Bamboo utilizes these and related resources to shape its User Interface development.
  3. Where sequenced (orchestrated?) execution of services is necessary to the production of information to be presented, an application layer of software services (in some methodologies referred to as a "task layer"), distinct from the User Interface, controls that execution. Application or task layer functionality may also include configuration and configurability, personalization, accessibility, and other (often less generic) function.
Technology Selection Criteria

Cf. Bamboo's "Lifecycle - Technology Selection Criteria page

Past Discussions - Minutes, Notes, and Follow-up thoughts

August 31, 2010 - "Patterns for Software Development"

The following notes are culled from discussion among Berkeley's IST-DS Architecture and Design team meeting of 31 Aug 2010:

  • A useful pattern for iterative development sprints, particularly where integration of the work of differently-located teams is in play, is: Dev Sprint | Dev Sprint | Refactor/Rearchitect Sprint
  • It is difficult to engage users for feedback in initial stages of a project large enough to require foundational work, because foundations aren't usually interesting to users and there's often 'nothing to see' until some amount of foundation-building is accomplished.
    1. It is critical to anticipate this problem, and to drive toward a stage of work that will most quickly engage users (whether 'end users' who evaluate a UI, or service consumers who evaluate a services API)
    2. Identifying and resolving strategic technical questions – rather than all technical questions – then driving toward modest implementation may be a strategy for success.
    3. Identifying areas in which "we are fighting our tools" may be a way of uncovering strategic technical questions
    4. It would be worthwhile to investigate whether this topic has been written about / discussed by respected members of the agile / extreme programming communities.
  • Any agile process requires a "no fear" or "it's okay to fail" ethos. This is not easy to build in the absence of time – and face time – so in a distributed project it is key for project leadership to work consciously at establishing and supporting this ethos. Failing early facilitates succeeding early.
  • It's important to acknowledge the organizational and institutional contexts in which software development occurs. When "first movers" gain some advantage or other circumstances occur to politicize adoption of design patterns, it is easy to commit to technically irrational decisions. This is a circumstance to be avoided.
    1. Relatedly, it is not possible, let alone easy – or even appropriate in all circumstances – to 'impose' professional software engineering standards on 'academically-embedded' IT organizations
  • No labels