I am looking for software technical solution document templates for my organization where we have requirement document from user groups and developer responsibility to produce solution document for the requirement doucment.
Any ideas on this are welcome, I understand anything in detail for technical spec would be more specific to an organization , but wanted to find out genrally for software development process (SDLC) what kind of templates that developer can adopt to explain what his code can/cannot do.
Thanks a lot
This Question has been solved and asker verified All Experts Exchange premium technology solutions are available to subscription members.
Experts Exchange has been collecting answers to technology questions since 1996…3 million and counting! If you have a question, chances are we already have your answer.
If you can't find the exact answer you're looking for, ask our exclusive community of 50,000 experts. You’ll get a personalized answer from a trusted professional.
Thousands of free tech tips, tricks, how-to’s and tutorials are available in our peer reviewed articles section. See for yourself how smart our experts are, no login required.
Save solutions to your questions, answers you’ve discovered through searching plus helpful articles in your personal knowledgebase for easy future access.
Access the answers to your technology questions today.
30-day free trial. Register in 60 seconds.
Members of the expert community talk about why the experience at Experts Exchange is different than what you will find anywhere else.
Try it out and discover for yourself.
30-day free trial. Register in 60 seconds.
Join the community of experts here and help other tech pros by answering question in your area of expertise. You can earn FREE access to all Experts Exchange's premium features and resources.
mahjag,
This could be a loaded question on this. Each organizations set standards from minimum to maximum requirements and contents of those. But a outstanding place to start is the UML tutorial http://www.sparxsystems.co
Our organization usually follows this procedure
1. User must first present an idea to our IT management and have a clear "expectation" of they want by providing a Request. This request doesnt goes in depth, but does explain what they want and any outside organizations that might interact with this request also.
2. From there we take a pre-liminary educated guess at a high level of what it will take in regards to hours and time schedule to complete the request
3. Next we go back to the "sponsor" and report to the how much time and effort it will take and find out if they will have the appropriate funding. If they may have part of it, we then scale down their initial request to meeting funding expectations.
4. Once step3 is done, we then begin a statement of work. This is high level form which basically states what we are going to do, how we are going to accomplish the task and the expected time frame. The User must then sign off on it.
5. Next we begin developing by having the user create use cases for what was signed off on step four. Our use cases look like below:
Use Case Diagram
a. Use Case Name: Name of Use Case
b. Unique Use Case ID: Use case number. This is assigned to a test case which will verify this was handled which the user will sign off on.
c. Primary Actor(s): Who will be doing this task the majority time
d. Secondary Actor(s): Who will be doing this task occasionally but not normally
e. Use Case Description: Description of use case function
f. Preconditions: What needs to happen before this use case is executed.
g. Flow of Events: Psuedo Code of events accomplished by this task (high level)
h. Postconditions: What needs to happen immediatly after this if needed.
i. Alternative Flows and Exceptions: What different paths might occur on abnormal or alternate paths.
j. Assumptions: What are needed for this use case to work successfully. (security, files, etc.)
i. Issues: This is a place for user to comment on unknowns that need resovling before this use case to successfully execute and they dont how to resolve
j. Requirement Document Source: Location of requirement documentation this use case was derived from.
6. From there is where you pick the pieces of the UML design for your designer and/or programmer to complete....
Like the previous posts, UML is a good start but every company use it slightly differently. Hence templates are kind of hmmmm... not exactly useful.
My firm uses UML and some of our own approaches to get things done. We learned from each projects and spends a week debriefing and refining our Software Design Protocols. Well, name it wharever you wish... :) UML is part of it.
Here's something you may like to consider... Where to begin when you have nothing much to work with.
Use LOGICS and Common Sense of what has worked and what hasn't to formulate the initial layout of processes. What i mean is simply, before UML there may be a few things you and your company like to layout.
UML is good when you start to design software. However, before designing we have some preliminary Research and Development to do, and how we should proceed and which technology we should use.
Here's a discussion on intro to UML..
http://www.experts-exchang
good Luck.
Hi Guys
Thanks for your responses.
I am really in a time constraint to produce a template for our technical solution document, I know this sound crazy as to getting the time to doing it correct, but first of UML would be big change to propose utleast given the timeframe to get everybody aboard,
First I want to look at sample template for software developers to write solution doucment as how the code should work and what happens if the code breaks.
Thanks a lot and please let me know if you can think on the same lines, all your input on this are appreciated, i did not mean to restrict the responses.
regarding the post question... Assuming if i didn't misunderstood the question, my simple view is like this...
Here's a extremely basic, generalized and simplified list of what we do when we get a customer:
[1] SALES
Usually sales people/manager will get a preliminary project briefing documents based on the customer's initial thoughts.
- Important: Not all customer knows what they want and what they're talking about.
- Don't waste time correcting them at this stage if you meet with them.
- Brief from Sales include information on:
- Introduction & History of the customer
- Customer's specialties/field/industry
- Customer's Technological Know-How and their Computer/MIS background
- Identify Problems that cause them to talk to us and expect more hidden issues.
- Payment Reliability Analysis (potential bad payment issues?)
- What they are requesting us to do/help them solve are documented.
If their views and ours on the solution is the same, no convincing needed.
- What they want to know and see on the coming technical meeting.
[2] TECHNICAL and SALES CONFIRMATION
I'll skip most details here except to say that it is here where we will Begin real work once the customer has commited to proceed.
- Research and Document SCOPE of solution.
- who will use the software & hardware at the customer's location?
- how old and computer literate are they?
- what are the PROBLEMS that we are hired WANT TO SOLVE?
- Hardware and Software integration requirements
- any odd/specialized/rare hardware or software requirements?
- IMPORTANT: Iron out all the questions, what is needed and who is needed to develop the solution, schedule and time of developments (hence costing), phases of development and deliveries, project management plans must be prepared.
- Finalize all details and prepare contractual agreements and quotations with all feature and software-hardware functions listed and defined by technical lawyers.
* Yes, when the project gets big, a single feature out of 100,000 can cause a project to collapse. Especially true when the customer doesn't want to pay and tries to renegotiate. Hence the lawyers gets their hands dirty before we do.
[3] NOW we DO the work.
At this point, we'll have clear and defined features and functions. Ironically the list of functions and features are all on paper - same from day one till the end. We make sure everything is completed and QA checked. Secondly we'll always throws in EXTRA MINOR features for FREE but was never mentioned.
- Features and Functionalities are layout in a tree fashion. Major, Minor, Sub-Layer and so forth. Name it whatever.
- A FOREST of TREES (FOT) of features and functionalies radiates from the center and spreads out on a huge whiteboard. At this point it's all non technical.
- Senior Designers, Leads and Engineers plan for the:
(1) Additional Research people are sent to the customer locations and design the software from the client's sites/centers. Usually about 1 week.
(2) Engineering Mehtodologies, Developments Specifications and Integration
(3) Identify Potential REDS zones (Danger/Unknown areas of developments)
(4) Identify Potential R&D requirements on untested grounds
(5) Software-Hardware Architecture specified.
(6) Assign members to team, hence development responsibility.
Team and Member responsibility documentations are prepared.
(7) PRIORITIES of jobs that need to be completed are listed and graded into the Forest of Trees (FOT) map.
(8) User Interface Specification and Implementation Stages are set.
- Layout and WorkFlow are mocked up on screen, and documented.
- Interactions between controls are discussed and planned.
- Lowest priority is given to icons and hot keys.
(9) Eventually a Comprehensive Development Guide is written by 2-3 people.
- A team splits into sub groups and handle different sectors of TREES.
- Every project is fairly different. Therefore we can't recycle most documents of come up with a comprehensive 'TEMPLATE'. What we do have is multiple apps we wrote that's like wizards which generates some of the documentations and store in a database.
[4] DEVELOPMENT CYCLE must be as simple and effective as possible.
- This is where planning human-hour and getting results is so crucial. Making U-Turns in design at this stage drives everyone crazy.
- Cycle of writing code, testing and debugging is actually fairly simple in concept. It never really is - when time and deadline draws near.
- It is important to have someone tracking every coding person's progress on a GANTT chart based on team and every Team's progress on it as well. only then you'll get a picture of how far are you into a project.
- Secondly, Quality Control is soooo dead crucial. You can finish fast, but full of bugs and cause much more serious headaches. Plan some code review responsibilities and have members in the team to review each other's work and SIGN OFF from it, befor emoving to the next part.
- Modular development will have Integration issues when things are not communicated between people. Hence having folks who hates each other can cause project serious hiccups.
* Refer to Enginneering Books on models and see what works for you. We started by trying one out and redefine and change it slightly for practical reason.
[5] THE REST
well.. it's the rest. Someone creates the manual, the icons, the deployement aspects. Huge time spent running the whole systems through the actual hardware with assorted testings methods, some manually. Other are either partially or fully automated (especially database related transactions and interactions).
- Run the data few million cycles and simulated 3-5 years worth of data. Check for anomalies and errors.
- Integrate all system log and auditing aspects.
- Errors and Anomalies tracking are instigated. Error Messages are check and minimized by auto-resolve as much as possible. Remove all technical ERROR messages
- Tests and more tests... maybe some rewrites of some codes here and there. Hence more tests.
- Backup measures
- Self-recovery mechanism. This actually can be dangerous if not careful.
- Test Redundancy components in hardware and software.
ABOUT QUALITY CONTROL
--------------------------
It's all about testing and testings till one goes screaming. It's so important tat it's crazy.
Quality Control is actually a huge part and is integrated from Top to Bottom. Do think about it before starting. Regression Tests are extremely important. Check for:
- Logical and Intermitten Errors
- System Anomalies based on incorrect configurations.
- Stupid Human Errors
- 5 cent or a nickel Errors (i.e. broken RJ45 or connection problem)
- Hidden Backdoor or Easter Eggs. They can and do cause errors.
Use Wikipedia to learn more about testings and software engineering issues.
I am off. Cheers and Good Luck.
Sorry, i can't quite post a sample or a template for a few reasons:
Software design has become fairly visual and has huge amount of diagrams. It doesn't make sense when I post only texts.
Secondly, i can get fired if the firm even thinks that i'm disclosing too much. It's part of the employment contract thingy.
Thoughts
------------
Moreover, what you want is a general Process & Flow of software design instead of a specific document.
What you are requesting is actually in UML. Since you don't have time to familiarize, try getting the concept of UML in your head but do it differently.
Lastly software development for small projects and larger ones are done differently. Generally i start with a Features MAP or FOT approach. Once you got the features map, you can try going into something similar to this:
Features <------> (Business) Logic
||
||
\/
Functions Creations (Not as in programming's "Function")
||
||
\/
Code
||
||
\/
Review
Code Breaks
---------------
Yeah.. This is the damnest thing in coding isn't it. I can say how other firms/people works.
Object Oriented principles is actually fairly neat. Think of it this way.. that you actually create Cities of people doing things. In a city, there a many companies doing different Functions. Cities are interconnected by highways, airports and trains - these are the connections type/methods between programming's modules.
Understand that and you'll know how things tend to crack. What happens when a Train runs on a Highway. What happens when a company (component) that relies on paper from another company (component) in another city (module)..
Unfortunately we cannot actually "SEE" these crashes until we see the symptoms of crashing actaully appears. Hence two concepts will come to mind:
[1] Predictive, Estimation and Identification of Potential Problem areas.
[2] Reporting and Logging of the Problems.
Can't do much on the [2]nd aspect 'cause.. it's usually about releasing fixes and updates.
However on the [1]st point, you could actually build many checks and balances into the software to HARDEN it from failing. The funny thing is that, it takes extra time from doing productive "seeable" and "functional" part of the software.
There're commercial software out there like DevPartner that does pretty good error checkings. I generally do 2 things, create Data Redundancy secondly Data formality validation.
This is actually a HUGE area in Computer Science. Microsoft has recently announced their predictive bug identification and tracking AI that it will be integrated into future programming.
Final Thought
----------------
I don't think we can actually do your work for you as we're not getting paid. Secondly, we're not CLOSE to your problem. Hence we cannot actually understand your FULL perspective on the matter as well as you do. You have a better chance of figuring this out than us.
One way to allow us to help you better is layout your problem in greater details - not all at once, but gradually as the post goes.
As far as i know, you'll only get some Sample Templates from educational classes or seminars as part of a course work.
I am leaving this place tomorrow and will be away. Good Luck
Sorry Jenn3 and MilanKM, but taking an interest in your company approaches, usually winds up in much laughter here; not at you, but at some of the things your report:
" . . . Microsoft has recently announced their predictive bug identification and tracking AI that it will be integrated into future programming."
I really can't stop laughing at that one! All of the intelligence in Redmond is artificial! hahaha, as if!
Secondly, you need to review your processes; you don't write the manual at the end, you write it as you go. Otherwise, the manual will not reflect the problems involved during development [in fact, Microsoft makes the best case for this because that is what they do, write it at the end, thus, it misses about 250,000 known bugs].
"Predictive bug Identification and Tracking" do they mean they're going to use SourceForge and CVS now? hahaha
They are so in the past!
"requirement document" = Scope of Work; that's all it is.
"solution document" = reports, much like RFC's, or, memoes and their responses
"software development process (SDLC) what kind of templates that developer can adopt to explain what his code can/cannot do." = big white paper board for teams, artwork for sales, that is, presentations and meetings.
Any set of process templates will do. Put them in a presentation program, like a slide show, and do what you see every corporate meeting in the movies do, suits, chairs, big oval or square table rented from some fancy hotel, you know the drill.
As for the flowcharts, these haven't changed for about an hundred years, diamonds, squares, circles, all those logic flowchart symbols. It's really no different than a plant meeting of engineers and designers at GM proposing a new car design and manufacture, it's all done with artwork.
So, you just need a common ground set of artwork tools.
There is one thing you may not have yet, a Virtual Machine Emulator. That is, a program that steps your code modules as they are written and shows the input and output with any error conditions as it steps.
If you just want the customer to bite, the question becomes "Lend me one of your employees that knows what you want it to do for a few days and we'll come up with a feasible solution."
Often, what goes back and forth on paper is neither what the customer wanted, nor what the software company produced.
A composition book for each team member wouldn't hurt either, just like at a lab in Los Alamos or Palo Alto. All notes in pen and ink, no pencils, all proprietary.
Start with your best template, like any succesful lawyer does, pen, ink, and a notebook.
Then dress it up with artwork and presentation, using the standard templates, squares, diamonds, circles.
And avoid politically correct isms that may alienate your customer, like "human-hours." If manhours, mandays, and manyears are not good enough for that customer, you don't want to do business with them anyway. Besides, the words are shorter and this saves time.
Work should be fun, not drudgery, find some applications that help with your artwork, the templates will produce themselves.
Business Accounts
Answer for Membership
by: MilanKMPosted on 2005-11-18 at 22:17:34ID: 15325105
Hi,
Not quite clear from ur question that about which type of development template/ technical specification ur looking for. Are u looking for some software paradigm?
:)