Skip to content

GitLab

Last edited by Rene Cabral
Page history
This is an old version of this page. You can view the most recent version or browse the history.

digitec software promises

Home / Digitec Coding Practices / Digitec Software Promises

Digitec Software Promises

Preamble

During the stages of client engagement, the project manager will request information from the software engineering department in order to make fulfillment promises to the client.

Software promises at Digitec can not be made without two official documents which are generated by the Software Engineering Department:

The Guidelines:

The only binding documents for software production are the SRS and the Time Estimate related to that SRS. All SRS must be approved by a Senior Software Engineer. All Software Architecture requirements must be approved by a Senior Software Engineer. All Server Deployment Architecture requirements must be approved by a Senior Software Engineer. All UI Mockups and interactions that must be realized through software (CSS, HTML, Javascript), require an SRS and its related Time Estimate.

Words matter, especially when you are legally binding yourself to the delivery of services. The language you use in the specification should observe a criteria that ensures clarity for both the developer (writer of the specification) and the client. As a rule both the developer and the client need to sign off on the specification before work begins.

It may be worth noting that at times the role of client can be played by the project manager or other personnel requesting the job. Although this specification is destined for internal use, it is just as necessary as one that is destined for a client.

The end result should be that the developer is ensured a properly scoped job, in which the requirements he must satisfy are clear. Any new requirements that come up can be confidently labeled out of scope and the developer is protected from having to fulfill them without a re-negotiation. For the client it means, a clear articulation of the job requirements which legally ensure that the client is getting what he paid for.

The following text is a great guideline for the type of language that you must use when writing a specification.

Specifications are printed documents that establish procedures and requirements for a particular project. Specifications are legally enforceable as contract documents and must be prepared with concern and respect of their legal status. Specifications should include the correct use of words and grammar with properly constructed sentences and paragraphs. Specifications must be clear, correct, complete, and concise using these guidelines:

  1. Clear: Use correct grammar and simple sentences to avoid ambiguity. Carefully selected words to convey exact meanings.
  2. Correct: Present information accurately and precisely.
  3. Complete: Do not leave out important information.
  4. Concise: Eliminate unnecessary words, but not at the expense of clarity, correctness, or completeness.
REF - OGS Design Procedures Manual - Specifications Language

A key point to remember in software specification is that you are writing from a users perspective, you are effectively describing everything that the user sees. You MUST stay away from mentioning implementation details. References to any process flow is acceptable as long as they are general and have an effect on what the user sees.

The Process

  1. Discovery: gather as much information about the project as you can. Interview as many people as you can. Project manager and/or implementor should speak with the client and relevant personnel. In some cases it may only be necessary for the implementor to speak with the project manager.
  2. Requirements: write down all the project requirements as you understand them. Feel free to categorize them into logical groups.
  3. Assumptions: write down all the general assumptions you have made regarding the project. These assumptions are part of the spec and help delineate the scope of the project. They can include, server software, supported browsers, data supplied in specific formats, etc.
  4. Consultation: if you are a project manager, you should always consult the implementor prior to finalizing the specification in order to identify gaps in functional assumptions, understandings of technology, as well as implied time commitments based on the complexity of the requirements. The goal of this meeting is to ensure that the specification is correct and that the participants agree on their understanding of the requirements.
  5. Client Agreement: the final specification if presented to the client; it is supposed to be an exact representation of the scope of the work. If the final specification leads to a conflict with client expectations then the requirements can be negotiated or adjusted to meet the clients expectations. In the latter case the cycle begins again at step 1.

Use Case

A simple use case is an upgrade request from Symantec on a tool we had previously built for them. After speaking with the project manager I scheduled an interview with the client. When all my questions were satisfied, I then put together the following specification:

Symantec Pricing Calculator Upgrade

  1. Performance Sizing
  • UI Changes
    • Symantec NetBackup Appliance Software version Pulldown will be added after appliance selection. The choices will be 2.5 and 2.6.
    • GB changed to TB throughout the sizing interface.
    • Performance sizing data collection screens will occur after capacity sizing. These pages will collect the data represented by the blue fields in the spreadsheet supplied by Mario Lukic on 1/27/14.
  • Logic Changes
    • After the capacity sizing calculations occur and the required capacity TBs are calculated we calculate the required throughput TBs using the performance sizing inputs and the calculation supplied.
    • Mario will supply Digitec with a formula that will allow us to determine whether the capacity TBs are enough to satisfy the throughput TBs. If the capacity TBs satisfy the throughput TBs we simply use the capacity TBs to give the recommendation. If the capacity TBs do NOT satisfy the throughput TBs we then adjust the required capacity TBs and proceed with the recommendation.
  • General Assumptions
    • If the software choice is 2.6 and sizing is chosen, you MUST use performance sizing.
    • Performance sizing will not be used for software version 2.5.
    • The data for recommendations for 2.6 will be submitted in the Digitec specified format.
    • There are NO additional SKUs to be added in this update.

Some Key Points

In the UI Changes, the requirement for GB changed to TB throughout the sizing interface has programming work associated with it: calculations need to be changed. The total time this requirement will take, will be calculated taking the programming work into account. The programming work is not mentioned because the result is never externalized to the user.

The requirements within Logic Changes are interesting because the part externalized to the user is just the result. The calculations supplied by Symantec are a key part of the work being done. The important thing to note is that the specification never goes into detail about the implementation of these, but simply references where the details can be found.