When preparing initial documents to describe a subcontracting project we have 4 distinct levels of documentation "depth" where each is more detailed than the previous one - and you don't necessarily need to document everything down to the lowest level in order to have a successful project
Level 1: User stories
User stories are a great way to abstract yourself from the technical minutia and to define top-level goals for the subcontracting project - they are the answers to "What?"
User story is a one-liner where you can describe your project goals to a person who is seeing the project for the first time and has no idea what you want to accomplish - never allow subcontractors to figure this out for themselves
Also a user story will make sure that the user (you) achieves clarity about the project goals before going down the rabbit hole
User story has a few elements:
a) "As a user" - this puts you in the proper set of shoes on start as you are the user
b) "of the <final deliverable>" - clarify what is the expected end deliverable of the project: an app, a component, an engine, documentation, specs, etc.
c) "I want to be able to <functional goal>" - one desired project use case
Some examples:
As a user of the application I want to be able to... (one goal what you want the application to cover, i.e. allow for browsing database encrypted objects, to be able to easily decrypt database objects)
As a user of the component I want to be able to... (visually view database objects in a form of a graph, manipulate database objects as a graph)
As a user of the engine I want to be able to... (access all of SQL Server instance properties in an object model form)
As a user of the functional specification I want to be able to... (have a detailed functional requirements breakdown for the engine mentioned above).
This specific user story is great for when creating specs-for-specs (see appendix)
As a user of the automated test I want to be able to...
All but the simplest projects will have more than one user story defined - i.e. one user story per needed application/engine feature
Level 2: Functional requirements breakdown
Once user stories are defined they can now be broken down into individual and more detailed functional requirements
Functional requirement is a free-form short description that further explains a user story
To breakdown a single user story "As a user of the visual component I want to be able to view database objects as a graph":
a) Each object type should be visually represented with a different geometrical shape
b) Related objects should be interconnected using lines
c) We should have several predefined presets / algorithms for object layouts
...
Functional requirements are short and don't go into details, i.e. what kind of geometrical shape should be applied to what type of object, how will object name be displayed, color of the shape, etc.
It is critical to invest as much time as needed to define all functional requirements that we need on start.
If we uncover that we've missed to define a functional requirement during the project then all such burden of additional requirements will fall down on us (as project appendixes that bear additional costs)
Level 3: Functional specification
Each of the individual functional requirements can be further broken down to create a functional specification / functional details
Consider each of the functional requirements as a new paragraph or a separate section with a freedom to go into all the tiny details
A section "Representing object types visually" can have:
a) A mockup / picture of a representative object type
b) List of default geometrical shapes, colors, text
c) List of configurable elements, and all required shapes to be available
...
Drawing up a good functional specification is very time-demanding and depending on the project scale and complexity it can be wise to consider subcontracting this work (see appendix)
Level 4: Technical specification
The lowest level of a subcontracting document is technical specs which can be more or less detailed, or can be skipped altogether
Almost every development subcontract will have some basic technical requirements in a form of required development technology, coding standards, etc.
Anything more than that is very risky as it effectively spoon-feeds the subcontractor and requires a lot of micromanagement time on your side thus making it questionable whether you should've worked on the project by yourself from the start
A good rule of thumb is to avoid technical specification whenever possible, or if really needed have subcontractors work on it prior to beginning any actual implementation/development work
For specific projects where it is important to go down to tech spec details level, try to keep it as short as possible
Appendix - Specs for specs
The main goal of subcontracting is to help you achieve team goals as quickly as possible (success = results / time)
Smart product teams will keep this in mind at all times and will not replace their development time with spec writing time
A smart product team will spin off subcontracting projects by focusing on writing up Level 1 (user stories) and Level 2 (functional requirements) subcontracting documentation
As such you can have subcontractors write Level 3 and Level 4 (functional and technical specification) documents themselves which you can later review and approve prior to starting the implementation
a) Know thy comps - research and figure out in details who we want to better / what we want to achieve
b) Know thy goals - write up good user stories by yourself what we want to achieve (Level 1)
c) Know thy needs - write up all functional requirements (Level 2)
d) Make it so - have subcontractors do the remaining work by writing the remainder of the project documentation prior to implementation
No comments:
Post a Comment