|
The design document is more than just a few pages of design stuff. The "design document" lives in spirit and name only and is comprised of several parts as well as a coherent underlying arcetechture. The design document is best represented by the following components:
1. A system design document.
2. An interface control document.
3. A system-level requirements document.
4. A software-level requirements document.
5. A requirements testing and tracibility document.
6. A software process and quality control document.
However, we need to take a few steps back before we can really go forward. We need to start at the preliminary design phase. This phase is the most informal phase of system design. This is where we start brainstorming over what the project entails and what it's final goals and visions are. We need to clearly discuss the need for our software, the problems and shortcomings it's going to solve, and how the customer will use it. We are really approaching the "sizing" phase. That is literally what it means, we begin to "size" the project and see how big or small everything really is. We then talk about the interface. How is the customer going to use our product? The interface is the most important aspect of the system because that's what the customer sees.
---ASIDE---
I use the term "customer" quite loosely. "Customer", as we need to define it here, is anyone who will be using our code, be it in terms of some final application, or as a functional library. We have both internal and external customers. Everyone on the team will be a supplier or a customer to another member of the team several times throughout the project lifecycle.
---/ASIDE---
---ASIDE2---
I remember going through this stuff in my senior design class and it made no sense to me whatsoever. It wasn't until I was out in the proverbial "real world" that I saw all this stuff in action. So in this light, I will try to clearly explain the design process as we go. If anything is vague or ambiguous, don't hesitate to ask for clarification.
---/ASIDE2---
Anyway, for a preliminary outline for the system design document, I would break it up as follows:
I. Abstract
A. What problem or shortcoming is the system going to solve?
(here we state the case for the project and justify why we are doing it)
B. How does the system solve that problem?
(high-level here, not too much detail)
C. How do you plan on implementing the system?
(process, not details!)
D. How do you plan on tracking progress?
(project-manager type stuff. waaay more on that later, it's a biggie)
E. How do you plan to prove the system does what it claims to do?
(the testing and QC processes go here)
II. Introduction
A. The Promlem / Shortcoming (whatever it is we're going to address)
1. Define the problem in detail.
B. Solution
2. Define the system-level solution here.
(everything here will be in terms of the external customer point of view)
III. Details
(here we introduce our other documents and provide their meaning and justification)
A. - F. (An overview of the documents listed above)
IV. Appendices
A. - ?. Timelines, schedules, org-charts, deliverable dates and milestones, etc.
Anyway, that's just a quick initial stab. These things don't take solid form overnight, they need to cure for a while... 
- Nitron
"Those that say a task is impossible shouldn't interrupt the ones who are doing it." - Chinese Proverb
|
|
|
|
|
1. General Information
a. What is the problem?
b. What is the proposed solution?
c. What is the cost benefit of the solution?
2. Current Practices/Procedures
a. How is this problem being solved currently?
b. Who is involved in the current process?
c. What are their responsibilities?
d. What processes/knowledge is "hidden", and by whom?
3. Changes To Practices/Procedures
a. What changes are proposed?
b. Who are the people affected?
c. How are their responsibilities changed?
d. What training/documentation support will be required?
e. Who maintains the new implementation?
4. Technologies
a. What existing technologies will be used?
b. What new technologies need to be developed?
c. Cost/Stability/Maintainability/Documentation of all technologies
5. Design Overview
a. High level concepts/components/modules/functions
b. Identification of concerns: high level interactions
c. Identification of interests: who needs to know what from whom? (not people but concepts)
d. Early identification of trouble spots
e. Prototypes required
f. Planned QA / Test bed processes
g. Instrumentation/Profiling plans
h. Documentation plans
i. Error management (hardware, third party, internal)
6. Detail Design
a. Flowcharts
b. State diagrams
c. Design Patterns--how will separation of concerns be implemented?
d. Data Management
1) data lifetime
2) data persistence
3) data transfer between components
e. User Interface Prototype
f. Database Schema Prototype
g. Error handling/recovery
h. Psuedo-code
7. Design Iteration
a. Identify areas of risk, requiring design review/changes
b. Identify areas of lack of information, requiring further design depth
c. Identify areas of innovation, suggesting risk, buy in problems, or maintenance problems
Marc
Help! I'm an AI running around in someone's f*cked up universe simulator.
Sensitivity and ethnic diversity means celebrating difference, not hiding from it. - Christian Graus
Every line of code is a liability - Taka Muraoka
Microsoft deliberately adds arbitrary layers of complexity to make it difficult to deliver Windows features on non-Windows platforms--Microsoft's "Halloween files"
|
|
|
|
|
A general comment on a project timeline. I think the project should be more functional driven, based on the vagueries of people's ability to work on things, and possibly that people might come and leave a project during it's development.
I think the project leads should have a very clearly defined functional milestone schedule. I have my doubts that a time-based schedule is necessary, enforcable, or useful.
Marc
Help! I'm an AI running around in someone's f*cked up universe simulator.
Sensitivity and ethnic diversity means celebrating difference, not hiding from it. - Christian Graus
Every line of code is a liability - Taka Muraoka
Microsoft deliberately adds arbitrary layers of complexity to make it difficult to deliver Windows features on non-Windows platforms--Microsoft's "Halloween files"
|
|
|
|
|
It would be nice for people to be able to see when you think things will be finished. If that can be accomplished in a milestone schedule, then thats fine.
As far as standard documents for projects, I would like to see some semblance of a timeline or a "time to reach goals" chart, or a projected milestones chart.
Jason Henderson latest CPP news
"If you are going through hell, keep going." - Winston Churchill
|
|
|
|
|
Requested by: Nitron
All Request For Comments (RFC) should be posted on my message board[^] where I will then post them here at the proper time.
BEGIN
=================================================
Nitron wrote:
When forming the teams, we will need to fill several positions:
Project Manager - responsible organize WBS / tasks / deadlines / deliverables
Systems Lead - responsible for keeping systems engineers on track
|
|----- Systems Engineers - responsible for system design and defining requirements
Software Lead - responsible for keeping programmers on task
|
|----- Software Engineers - responsible for implementing system requirements
Test Lead - Responsible for keeping testers on track
|
|----- Software Testers - responsible for verifying bulletproof code
|
|----- System Testers - responsible for independently verifying system requirements
Configuration Managment Lead - responsible for versioning / bug tracking / problem resolution
|
|----- Quality Control - responsible for CM and formal release procedures
Then aside from coding, we need graphics artists, marketing, and support personnell.
This will provide well defined roles and create synergy within the teams.
=================================================
END
NOTE:<br />
Keep in mind how I would like to see the article series structured. See <a href="http://www.codeproject.com/script/comments/forums.asp?forumid=1645&df=100&app=50&select=514096#xx514096xx">this post</a>[<a target=_blank title='New Window' href="http://www.codeproject.com/script/comments/forums.asp?forumid=1645&df=100&app=50&select=514096#xx514096xx">^</a>] for more info.
Jason Henderson My articles
"The best argument against democracy is a five-minute conversation with the average voter." - Winston Churchill
|
|
|
|
|
Good! So, how will we go about choosing people for various capacities? I suppose the first stage is to have people say what they think they'd be able to do best.
I could fill the following roles:
Quality Control
Systems Engineers
Graphics Artists
Coder (  )
As always, if you don't want this here, let me know.
"Blessed are the peacemakers, for they shall be called sons of God." - Jesus
"You must be the change you wish to see in the world." - Mahatma Gandhi
|
|
|
|
|
jdunlap wrote:
So, how will we go about choosing people for various capacities?
That's not really what the RFC is about. Think in terms of what the team structure should be, not how to fill the positions. The leadership assignments will be handled by the project leaders in whatever way they wish.
jdunlap wrote:
Quality Control
Systems Engineers
Graphics Artists
Coder
These are what the RFC is about, so maybe elaborate on what these positions do.
jdunlap wrote:
As always, if you don't want this here, let me know.
If I didn't want comments, I would have said so.
But this is a "Request For Comments" message. 
Jason Henderson My articles
"The best argument against democracy is a five-minute conversation with the average voter." - Winston Churchill
|
|
|
|
|
Jason Henderson wrote:
The leadership assignments will be handled by the project leaders in whatever way they wish.
So the project leaders will choose their own method of assigning capacities. Makes sense.
Jason Henderson wrote:
These are what the RFC is about, so maybe elaborate on what these positions do.
Where should I do that? (Sorry, I know I'm being a little slow at catching on to the forum setups.  )
"Blessed are the peacemakers, for they shall be called sons of God." - Jesus
"You must be the change you wish to see in the world." - Mahatma Gandhi
|
|
|
|
|
A couple comments (that's what these are for, right?)
1. Needs a section for documentation generation and management
2. At minimum, this describes 10 people (well, 12 if you include Documentation Manager and technical writer). Of course, in reality, several of these jobs will probably be combined or shared by one or more people. I for one am very fuzzy as to some of these terms. How is a system lead different from a software lead? What's the difference, functionaly, between a lead and an engineer/tester? I think this really needs a glossary.
3. Too formal. Results in compartmentalization.
4. Too early to do this. This structure can't be supported if there's 2 people on a project, for example. Structures like this are valuable when there's at least one person to fill in every slot (arguably, maybe .5 persons).
5. I'd rather have the project leads pick their organizational model. There are other ones besides this that would fit better, in my thinking, with the dynamic nature of this kind of effort (as in, people contributing their spare time on a voluntary basis).
Marc
Help! I'm an AI running around in someone's f*cked up universe simulator.
Sensitivity and ethnic diversity means celebrating difference, not hiding from it. - Christian Graus
Every line of code is a liability - Taka Muraoka
Microsoft deliberately adds arbitrary layers of complexity to make it difficult to deliver Windows features on non-Windows platforms--Microsoft's "Halloween files"
|
|
|
|
|
Marc Clifton wrote:
1. Needs a section for documentation generation and management
Agreed. Someone is going to have to do this, so it would be wise to delegate this responsibility.
Marc Clifton wrote:
2.
Some of these terms are fuzzy, but they should be defined here in more depth.
Marc Clifton wrote:
4. Too early to do this.
It won't hurt to discuss this and give PLs more idea on how to do this.
Marc Clifton wrote:
5. I'd rather have the project leads pick their organizational model.
I agree, but would it not be advantageous to define a minimum standard model for the leadership structure? Maybe standard is the wrong word. How about recommendation?
Jason Henderson My articles
"The best argument against democracy is a five-minute conversation with the average voter." - Winston Churchill
|
|
|
|
|
Marc Clifton wrote:
Of course, in reality, several of these jobs will probably be combined or shared by one or more people.
Yes. I'll probably end up in more than 1 job. 
Marc Clifton wrote:
How is a system lead different from a software lead?
The software lead leads the creation of the software, and the systems lead leads the care of the systems the devs work with (CVS, etc).
Marc Clifton wrote:
What's the difference, functionaly, between a lead and an engineer/tester?
the lead coordinates the work, the engineer does the work.
"Blessed are the peacemakers, for they shall be called sons of God." - Jesus
"You must be the change you wish to see in the world." - Mahatma Gandhi
|
|
|
|
|
Well, yes, I suppose that's obvious, but these things really need some formal definition so people know what is expected of them. Personally, I think it's too management topheavy.
Marc
Help! I'm an AI running around in someone's f*cked up universe simulator.
Sensitivity and ethnic diversity means celebrating difference, not hiding from it. - Christian Graus
Every line of code is a liability - Taka Muraoka
Microsoft deliberately adds arbitrary layers of complexity to make it difficult to deliver Windows features on non-Windows platforms--Microsoft's "Halloween files"
|
|
|
|
|
Marc Clifton wrote:
Personally, I think it's too management topheavy.
And it would be, except that one person can take more than one role. It would be nice if people could "slide" into it according to their abilities, but I don't know how that would work. Maybe in the course of discussions, we will get some kind of idea of who will do best at what.
"Blessed are the peacemakers, for they shall be called sons of God." - Jesus
"You must be the change you wish to see in the world." - Mahatma Gandhi
|
|
|
|
|
Marc Clifton wrote:
Personally, I think it's too management topheavy.
Me too
- Anders
Money talks, but all mine ever says is "Goodbye!"
|
|
|
|
|
First off wanted to say thank you Jason. You've done a great job so far and we wouldn't be this far without your lead. ![Rose | [Rose]](https://codeproject.global.ssl.fastly.net/script/Forums/Images/rose.gif)
As for the proposed structure. I like the fact that it lays out roles. Who fills the roles should be up to the PLs for each project. While this particular structure may not be the best in the opinion of everyone, I think it is a good start.
No doubt some individuals will fill more than one role. Some roles will have more than one person. The PL will probably fill most of the lead roles.
The structure lays out an important timeline of how to proceed.
1. We gather resources (people) for each project. (PL)
2. Then divide assignments to each person based upon qualifications and strengths. (PL)
3. Then define requirements for the project. (Those interested in project, or just involved)
4. Decide what will be included in first rev. Keeping in mind that the shorter the dev cylce the more likely success. Future revs to follow. (PL and leads)
5. Requirements defined and documented (Systems Engineers)
6. Review and testing of requirements to ensure everything in order. (System Testers. Should not be same as Systems Engineers. Never debug your own work.)
7a. Once requirements approved by PL coding begins. (Software Engineers)
7b. In parrallel, Test plans are created and documented based upon requirements documentation. (Software Testers)
8. Coding completed and reviewed by testers. Modifications made if discovered. Additional tests documented based upon specific code segments.
9. Testing done and results reviewed.
10. Fixes made due to test results.
11. Repeat steps 8-10 as necessary.
12. Product release.
As for QA, this would be active throughout entire process. They would be integral in code reviews. Code reviews should be periodic and not wait till end. Final code review for purposes of forming new tests.
--
"The money power of the country will endeavor to prolong its rule by preying upon the prejudices of the people until all wealth is concentrated in a few hands and the Republic destroyed."
-- Abraham Lincoln
|
|
|
|
|
Firstly, the intent wasn't to formally structure or "compartmentalize" a team. I just wanted to formally identify roles that define a well balanced software team. As was mentioned, some people will likely fill several roles at the same time, while others may not. So for a clearer definition of the terminology, consider this:
Systems Lead - When assuming this role, you need to view things from the system-level. That is, not to have vision clouded by the details of the bug you spent all morning trying to fix. A system-level view has one target audience: the customer. What does the customer need? (Remember, the customer most likely doesn't know what they want.) How do you plan to meet that need? Is the current design in line with the project goals and mission statement? The systems lead has the highest view of the project, sometimes higher even than the project manager.
Systems Engineer - These people carry out the system-level objectives and produce concrete output in terms of documentation and system design. The systems engineer carefully considers the customer's need and approaches it with a software mind. The systems engineer takes these high-level goals and visions and breaks them down into system-level requirements. That is, functional requirements that are divided into manageable and logical components that, when all met successfully, roll up into a deliverable product and lead to a happy customer.
Software Lead - The software lead is different than the systems lead in that the level of requirements is lower. Rather than dealing with global high-level requirements, the software lead has a logical set of functional requirements from which to work. This is where the rubber meets the road so to speak. The software lead considers things like the actual implementation of a certain module of code. (Notice the systems engineer never even came in contact with the mechanics of the actual implementation.) The software lead keeps the software engineers focused and on task.
Software Engineer - These are the individuals responsible for designing the detailed mechanics of an implementation and actually coding it. In all aspects, these individuals are more involved than the proverbial "code-monkey". In this infrastructure, the software engineer commits more than just code to the project, they commit experience and design. The software engineer has a dark side as well... Just as the systems engineer documents and delivers system-level functional requirements, the software engineer is responsible for documenting the design and mechanics of the actual implementation. These design considerations will become a requirements specification in and of themselves, those of which will have been implemented either by the software engineer himself, or maybe even given to one of the aforementioned "code monkeys" to implement the detailed design.
Test Lead - I believe testing is the most crucial aspect of software development and the most expensive task to tackle for software houses. If a software project is going to skimp to meet a deadline, it's the testing that gets the axe first. With a resource pool of this size and quality (and the fact no one's getting paid here), I feel it is paramount that we not skimp on this aspect at all. In this light, the test lead is responsible for managing two teams. A software test team and a system test team. I will explain these in more detail next, but they are two separate terms. The test lead is the liaison between all the functional groups. Think of it in terms of verification and validation. First, we need to verify that all functional requirements are met, then we need to validate that the requirements are satisfactory to fulfill the needs and intentions of the system. Any anomalies found in the testing phase are to be formally documented and addressed by an anomaly committee.
Software Testers - Software testers are basically unit-testers. They test individual functions and implementations at their lowest level and throw every bad coding practice they can at the code. Their goal is to break the implementation at any cost (within engineering and common software reason of course). They reference the software engineer's documentation and look for holes and shortcomings in requirements. They are basically verifying that no stone is left unturned.
System Testers - System testers put it all together and test the software as it's intended to be used. I like to break system level testing out even further to two categories: 1. Failure-Mode testing. and 2. End-User testing. In failure-mode testing, the system tester intentionally fails (or tries to fail the system). How does the system respond? Will it be easy to figure out what went wrong from the end-user point of view? Are error messages understandable and consistent? Then end-user testing is just that. The software is being tested as it will be used by the customer. This is the "alpha" stage of development, full-up software (mostly), being tested as it's going to be used. However, don't think testers get off that easy... They have their own set of documentation as well. As the software tester tests to the software engineer's documentation, the system tester tests to the systems engineer's documentation. This is the "validation" portion. Do the requirements laid out in the system design meet the needs of the customer?
Configuration Management Lead - Ahh yes, everyone's worst nightmare.... (next to QC of course ) This person keeps tabs on all the details. As a CM lead, you are responsible for which version of software is where, who's working on what, what anomalies are outstanding and what level of severity do they carry with them, are the people doing what they documented they are doing. etc... We'll get way more into detail on this as time goes on...
QC/et.all - These individuals are responsible for keeping tabs on everybody. They are also responsible for documenting process and insuring everyone follows that process. They also sign-off on formal software releases. (more on them later too)
Well, I hope that clears up some stuff. We'll expound on all this in more detail as we move along.
- Nitron
"Those that say a task is impossible shouldn't interrupt the ones who are doing it." - Chinese Proverb
|
|
|
|
|
That was fantastic Nitron, a wealth of knowledge and good sense.
I certainly see us putting together a CPSF (Code Project Solutions Framework) for developing software. We cannot just come out of CP2 with just applications. We should come out with a strong process model as well. From the sounds of it you would be the lead of that project
Paul Watson
Bluegrass
Cape Town, South Africa
Chris Losinger wrote:
i hate needles so much i can't even imagine allowing one near The Little Programmer
|
|
|
|
|
Paul Watson wrote:
That was fantastic Nitron, a wealth of knowledge and good sense.
... it happens every now and then. 
- Nitron
"Those that say a task is impossible shouldn't interrupt the ones who are doing it." - Chinese Proverb
|
|
|
|
|
I'm not sure I really like that structure, it needs a lot of people.
To be honest it looks like something they use at IBM or other big old compagnies
I think the project lead should pich his own structure, because the structure always depends on the team, and the people on the team.
- Anders
Money talks, but all mine ever says is "Goodbye!"
|
|
|
|
|
Anders Molin wrote:
I think the project lead should pich his own structure
I think so too, but are there any basic roles you think need to be filled? Examples: Source Manager, Tech. Writer, QA Manager, etc.
Jason Henderson My articles
"The best argument against democracy is a five-minute conversation with the average voter." - Winston Churchill
|
|
|
|
|
Of course there is, but I don't know all of them before I see the tools we have to work with here on CP, and before I see the size/type of my team 
I hate when people make rules, saying we are going to do it this way, and then they force the team to work like that.
I love flexibility, and like to make the rules so they fit the team, this way your team is more happy, and if you do it right, you get a better product.
- Anders
Money talks, but all mine ever says is "Goodbye!"
|
|
|
|
|
Don't get me wrong, I don't want to force rules on you. These posts are just requests for comments that will help these projects get off the ground and on the right path.
Jason Henderson latest CPP news
"If you are going through hell, keep going." - Winston Churchill
|
|
|
|
|
Anders Molin wrote:
I'm not sure I really like that structure, it needs a lot of people.
Please, don't think of it as "structure". That was a bad term. Think of it as an offensive lineup, or the types of players that need to take the field during a pariticular play. I bascially gave an overview of an entire (american) football team. You need an offense, defense, and kick-off/punt/fieldgoal speciality teams, each customized for their task. The flexibility is there for project leads to do as they choose, but somehow in some form those roles need to be filled. I am not saying one person per role, several people will fill several roles, that is certain. I do however feel that you cannot deliver an SEI level 3 or higher product with any of those roles missing. (especially as the projects get larger and more ambitious)
Anders Molin wrote:
To be honest it looks like something they use at IBM or other big old compagnies
Relative to other areas of engineering disipline, software engineering is quite new, and is in need of some form of measurement of quality IMO. It's not intended as an imposing paradigm but as a standard against which to judge.
- Nitron
"Those that say a task is impossible shouldn't interrupt the ones who are doing it." - Chinese Proverb
|
|
|
|
|
OK, its been done before, but as I am a possible runner for PL in this project (subject to Tom Welch coming back), I wanted to get the ball rolling on this.
Any suggestions on the library and what should be in it can be posted on my Message board[^] as well.
So get going people. I saw an earlier post with a long list of suggestions, so I will be looking at that again as a good starting footprint.
Roger Allen
Sonork 100.10016
Were you different as a kid? Did you ever say "Ooohhh, shiny red" even once? - Paul Watson 11-February-2003
|
|
|
|
|
You're not really gonna call it UGLY are you?
I think GUILD or FLUID are better names.
------- signature starts
"...the staggering layers of obscenity in your statement make it a work of art on so many levels." - Jason Jystad, 10/26/2001
Please review the Legal Disclaimer in my bio.
------- signature ends
|
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
