| ... | ... | @@ -7,85 +7,48 @@ |
|
|
|
|
|
|
|
###### Overview
|
|
|
|
|
|
|
|
It is worth noting that, as a general rule, implementors are discouraged from creating the specification for a project that they will be working on. Implementation details tend to cloud and weaken the conceptual integrity of a specification. Thus, it is preferred that the project manager be responsible for creating the specification.
|
|
|
|
The Agile Manifesto introduced the umbrella term `Agile Software Development` in 2001. This term describes a group of software development methods based on iterative and incremental development, where requirements and solutions evolve through collaboration between self-organizing, cross-functional teams.
|
|
|
|
|
|
|
|
The roots of the methods used at Digitec originate with Extreme programming, which was a predecessor to Agile.
|
|
|
|
|
|
|
|
Extreme Programming (XP) is a software development methodology which is intended to improve software quality and responsiveness to changing customer requirements. It advocates frequent "releases" in short development cycles, which is intended to improve productivity and introduce checkpoints at which new customer requirements can be adopted.
|
|
|
|
|
|
|
|
Some Scrum methods are used for production versions of large projects.
|
|
|
|
|
|
|
|
###### REF - [Agile Software Development](http://en.wikipedia.org/wiki/Agile_software_development)
|
|
|
|
###### REF - [Extreme programming](http://en.wikipedia.org/wiki/Extreme_Programming)
|
|
|
|
###### REF - [Scrum](http://en.wikipedia.org/wiki/Scrum_(software_development)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### The Guidelines:
|
|
|
|
---
|
|
|
|
For large projects we use an abbreviated form of the IEEE SRS standard which relies on the functional requirements section. This document is also a great overall reference for learning about software specifications.
|
|
|
|
###### REF - [830-1998 - IEEE Recommended Practice for Software Requirements Specifications](https://vc.digitec.local/digitec/digitec-wiki/blob/master/wiki-assets/files/specification/IEEE%20830-1998-SRS-template.pdf)
|
|
|
|
---
|
|
|
|
In every specification, unambiguous language is of paramount importance and to that end it is useful to reference the _Key words RFC_ which clearly specifies the use of the words:
|
|
|
|
"MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL"
|
|
|
|
###### REF - [Key words for use in RFCs to Indicate Requirement Levels](https://vc.digitec.local/digitec/digitec-wiki/blob/master/wiki-assets/files/rfc/rfc2119.txt)
|
|
|
|
---
|
|
|
|
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 Process
|
|
|
|
|
|
|
|
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.
|
|
|
|
What I have found is that you need to design and tailor the agile process around the team, and some elements vary on every single project.
|
|
|
|
|
|
|
|
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.
|
|
|
|
Today what I use I would still call Agile Software Development (using healthy doses of XP and SCRUM):
|
|
|
|
|
|
|
|
###### REF - [OGS Design Procedures Manual - Specifications Language](https://vc.digitec.local/digitec/digitec-wiki/blob/master/wiki-assets/files/specification/OGS_050201SpecificationsLanguage.pdf)
|
|
|
|
No one writes a line of code without a specification.
|
|
|
|
|
|
|
|
---
|
|
|
|
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.
|
|
|
|
We divide every project as follows (Extreme programming terms on right):
|
|
|
|
|
|
|
|
---
|
|
|
|
Project Name (Epic )
|
|
|
|
Version (Iteration)
|
|
|
|
Milestone (User Story)
|
|
|
|
Issue (Task)
|
|
|
|
|
|
|
|
### The Process
|
|
|
|
We have various fancy information radiators on this like unit testing, functional testing, behavior testing, continuous integration, etc.
|
|
|
|
|
|
|
|
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.
|
|
|
|
Software versioning is intimately tied to the process and usually a trigger for the radiators.
|
|
|
|
|
|
|
|
### Use Case
|
|
|
|
Teams have a short meeting every single morning in which each developer goes over what (and how) they did yesterday, what they hope to get done today (and how) and ask any questions that they have.
|
|
|
|
|
|
|
|
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:
|
|
|
|
Milestones are usually two weeks long and we do make the deadline sacred at the expense of task completion (this can vary per milestone).
|
|
|
|
|
|
|
|
---
|
|
|
|
#### 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.
|
|
|
|
All of these constructs (except the meetings) are managed through software and automation.
|
|
|
|
|
|
|
|
---
|
|
|
|
#### Some Key Points
|
|
|
|
We also follow open coding standards for the languages we use and publish our own coding style guide which is based on open standards and well as some of my personal preferences.
|
|
|
|
|
|
|
|
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.
|
|
|
|
Specifics aside, thats pretty much it.
|
|
|
|
|
|
|
|
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. |
