|
Requested by: Jason Henderson
All Request For Comments (RFC) should be posted on my message board[^] where I will then post them here at the proper time.
BEGIN
=================================================
We need templates or guidlines for writing some critical documents.
1) Design Document
2) guidelines for enhancement suggestions or initial ideas (may not be critical)
3) Project Timeline
4) QA checklists?
First of all, do we need some of these? Which do you think are necessary and which aren't (and why)? Any others?
Second, what needs to be in these documents?
If you have some templates, please submit them for review... somehow. 
=================================================
END
Jason Henderson My articles
"The best argument against democracy is a five-minute conversation with the average voter." - Winston Churchill
|
|
|
|
|
Design document - ESSENTIAL - so that we know what we're doing and how we're doing it, and what we're not doing. I can help out with this. I'm designing a template, and if I like it myself, I'll upload it to my only hosting area that has space.
guidelines for enhancement suggestions or initial ideas - ???
Project Timeline - we should outline a project timeline, but we probably won't stick to it (although, of course, we should try to ).
Jason Henderson wrote:
QA checklists?
For some reason, this term doesn't ring a bell with me. (DOH)
"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:
guidelines for enhancement suggestions or initial ideas
how they should be submitted to the team for review
jdunlap wrote:
Project Timeline - we should outline a project timeline, but we probably won't stick to it
we need a basic template for this type of document since I think we need one too.
jdunlap wrote:
QA checklists?
For some reason, this term doesn't ring a bell with me. (DOH)
Quality Assurance (testing) checklists
Jason Henderson My articles
"The best argument against democracy is a five-minute conversation with the average voter." - Winston Churchill
|
|
|
|
|
There was one further design document we need. A coding standard, so that code developed by various people all has the same layout/naming convensions.
This can have a big effect as people will not have to re-work what they have developed to bring it all into one cosistent layout.
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
|
|
|
|
|
Roger Allen wrote:
There was one further design document we need. A coding standard, so that code developed by various people all has the same layout/naming convensions.
Good point.
What standards would you like to use for your project?
Jason Henderson My articles
"The best argument against democracy is a five-minute conversation with the average voter." - Winston Churchill
|
|
|
|
|
Jason Henderson wrote:
What standards would you like to use for your project?
Not Hungarian Notation 
- Anders
Money talks, but all mine ever says is "Goodbye!"
|
|
|
|
|
I hate it too.
I alwas start my ints with i's not n's. 
Jason Henderson My articles
"The best argument against democracy is a five-minute conversation with the average voter." - Winston Churchill
|
|
|
|
|
I have been working on project where some people used Hungarian Notation, and some did not.
It was really not a big issue, because we accepted the others style, and everyone was happy because they could code using their own style...
- Anders
Money talks, but all mine ever says is "Goodbye!"
|
|
|
|
|
Telling your team how to write readable code is a good thing.
You're not going to change the way a particular team member writes code in a general sense, but you can tell them what is acceptable and what isn't.
int i; // bad
int iCounter; // good
int iCounterForJasonsWidgetClass; // too much
That sort of thing.
Jason Henderson latest CPP news
"If you are going through hell, keep going." - Winston Churchill
|
|
|
|
|
What about
for (int i = 0; i < 10; i++)
{
}
- Anders
Money talks, but all mine ever says is "Goodbye!"
|
|
|
|
|
there are exceptions 
Jason Henderson latest CPP news
"If you are going through hell, keep going." - Winston Churchill
|
|
|
|
|
Anders Molin wrote:
Not Hungarian Notation
I am not a fan of hungarian notation, but it is useful when its limited in some ways:
m_ for a member var
s_ for a static member var
m_bVariable for bools/flags
I don't really care about the rest, as long as its descriptive so you can tell what a variable is for!
Whats really more important is the encapsulation and const correctness of the code.
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
|
|
|
|
|
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
|
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
