Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 7 years ago.
Improve this question
So basically I am looking for good templates for writing both technical and functional specs on a project or work request.
What do you use? How deep do you get while writing the specs? Any additional general tips you could provide would be appreciated.
My company needs these badly. I work for a contractor and right now we do not use these documents at all.
EDIT: I have read Joel's take about Painless Specification, I really liked it, but are there any other opinions :)
On general tips;
We are implementing a process of
1) Business Requirements Statement (BRS)
2) Functional Specification
3) Technical specification
The BRS covers what the business problems are, and what the requirements are around solutions, testing, security, reliability and delivery. This defines what would make a successful solution.
The functional spec details what is needed, how it should look, how long fields should be, etc.
The technical spec details where the data comes from, any tricky code that may need to be considered.
The customer owns the requirements. The developers own the tech specs, and the functional spec is a middle ground. Testing is done against the tech specs (usually unit testing) then against the functional specs (usually system testing) and then against the requirements (UAT).
The important part of this (and we are struggling with) is that the developers still need to deliver to the functional spec, and the original business requirements. In reality the functional and tech specs are just there for clarity.
In short, my main tip is to first work out the process you wish to implement. Then seek agreement from all parties involved in your proposed process, then work on the templates to fit. The templates themselves are only are a small part of the change you want to make.
Not a template, but Joel has written a couple of articles on writing a functional spec. He also has sample here.
You can buy templates from ieee and other places, but I have always ended up making my own.
For a technical spec, "Code Complete" by Steve McDonnell has a good checklist, you can draw some info from that. At my last job, I just made a template out of his section headers, and tweaked it from there.
As far as a functional spec, the important thing is to define all the interfaces:
UI (screen mockups)
Software interfaces (plugins, etc.)
Hardware interfaces (if appropriate)
Communications interfaces (Services, email, messaging, etc.)
There should also be a section for business rules, things that are important functionally that are not covered in any interface definition.
If you want to purchase a book, Software Requirements by Karl Wiegers has templates for a few documents as an appendix. Unfortunately, I'm at work and that particular book is at home. If someone has it handy, they might be able to confirm that.
I happen to like this one, among others: ReadySet.
He sells a pro version too.
This is the best one I have found: http://www.jiludwig.com/templates/FRDTemplate.doc
Start off simple, and work your way from there. Since this is your first experience working with this, use a word document with bullet points. Write it, re-read it and provide enough detail that it makes sense. For technical specifications, you may want to lead the developer toward a solution, but for functional specifications the "how" should be completely missing.
I would suggest to have a look at the Roberston's Volere template here. They are part of the Atlantic Systems Guild, together with people like Tom DeMarco and Timothy Lister of "Peopleware" fame.
As the template is copyrighted, I will not reproduce it here, but give you some of the main headers:
The Purpose of the Project
The Stakeholders
Mandated Constraints
Naming Conventions and Terminology
Relevant Facts and Assumptions
The Scope of the Work
Business Data Model and Data Dictionary
The Scope of the Product
Functional Requirements
Look and Feels Requirements
...
There are many more, but this should give you an idea. The most interesting part of the template is the requirements shell that lists functional requirements on a kind of cue card. Again copyrighted, but truly valuable.
Look here in chapter 9.
Related
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 4 years ago.
Improve this question
I am currently working on a project where a lot of user interaction is going to take place. There is also a commercial side as people can buy certain items and services.
In my opinion a good blend of user interface, speed and security is essential for these types of websites. It is fairly easy to use ajax and JavaScript nowadays to do almost everything, as there are a lot of libraries available such as jQuery and others. But this can have some performance and incompatibility issues. This can lead to users just going to the next website.
The overall look of the website is important too. Where to place certain buttons, where to place certain types of articles such as faq and support. Where and how to display error messages so that the user sees them but are not bothering him. And an overall color scheme is important too.
The basic question is: How to create an interface that triggers a user to buy/use your services
I know psychology also plays a huge role in how users interact with your website. The color scheme for example is important. When the colors are irritating on a website you just want to click away. I have not found any articles that explain those concept.
Does anyone have any tips and/or recourses where i can get some articles that guide you in making the correct choices for your website.
Adhere to some standard UI Design Principles:
The structure principle: Your design
should organize the user interface
purposefully, in meaningful and
useful ways based on clear,
consistent models that are apparent
and recognizable to users, putting
related things together and
separating unrelated things,
differentiating dissimilar things
and making similar things resemble
one another. The structure principle
is concerned with your overall user
interface architecture.
The simplicity principle: Your
design should make simple, common
tasks simple to do, communicating
clearly and simply in the user’s own
language, and providing good
shortcuts that are meaningfully
related to longer procedures.
The visibility principle: Your
design should keep all needed
options and materials for a given
task visible without distracting the
user with extraneous or redundant
information. Good designs don’t
overwhelm users with too many
alternatives or confuse them with
unneeded information.
The feedback principle: Your design
should keep users informed of
actions or interpretations, changes
of state or condition, and errors or
exceptions that are relevant and of
interest to the user through clear,
concise, and unambiguous language
familiar to users.
The tolerance principle: Your design
should be flexible and tolerant,
reducing the cost of mistakes and
misuse by allowing undoing and
redoing, while also preventing
errors wherever possible by
tolerating varied inputs and
sequences and by interpreting all
reasonable actions reasonable.
The reuse principle: Your design
should reuse internal and external
components and behaviors,
maintaining consistency with purpose
rather than merely arbitrary
consistency, thus reducing the need
for users to rethink and remember.
Try to look for Websites or Web Application which has successfully achieved the goal you are looking to achieve, study their UI's, try to find common parameters & patterns which engages the user on their sites.
I always believe amazon is very good at keeping user engaged on website by showing relevant recommendations, what other people are looking types recommendations, people who bought this also bought this kind of recommendations.
Another good read: What should a developer know about interface design usability and user psychology
Also, Good Read on UI design considerations of e-commerce websites.
When it comes to UI design, ideally you will have an actual visual designer provide some guidance on your use of colors and a UxD provide some insight into your layout and flows based upon their expertise in these areas. Barring these folks having some input, if you design the pages and create the visuals yourself, iterative discovery is the best method to inform your design and provide insight into how these items affect the user and the overall experience you have created.
While there are certainly numerous books you can read and "guidelines" you can follow (and should for the initial design phases), no amount of book learning can replace real user interactions.
Build a functional prototype of your site/app/service/etc. and get it in front of actual users to gauge usability and value. This should be done in an ad-hoc format (versus formal usability testing) and the prototype should consist of smoke and mirrors as needed (i.e. it could be only clickable comps or primarily images with only the flows you're testing actually working).
Once you have some level of prototype, bring it to a place where ppl tend to be (and where you have i-net access if needed). I have found Starbucks to be great for this. Grab some ppl and ask if you can have 10 minutes of their time - you'll find tons of willing participants. Provide these folks with a simple / specific scenario to complete in your prototype and watch and learn.
People in a real-world situation using your software will quickly find its flaws and you'll be learning more than you could ever glean from a book or guideline. You'll be iterating on the design and tweaking items every time you test.
Test like this over a few weeks and you'll be discovering the perfect design very quickly. Once you have something that ppl can use and find value in, you're ready to get it live. But, testing should not end there - once live, you should continue to test and tweak via A/B and multi-variant testing while keeping a close eye on on your analytics and user behavior.
Discovery testing followed continual A/B allows you to continuously tweak, test and learn and ultimately to create the best solution possible.
Closed. This question is off-topic. It is not currently accepting answers.
Want to improve this question? Update the question so it's on-topic for Stack Overflow.
Closed 10 years ago.
Improve this question
As we are a small company, I work as both a project manager and developer. The specifications I create for clients contain a number of elements used to describe and define the project, including user stories alongside any other elements I feel need to be included to define the project (e.g. wireframes, userflows, sitemaps etc.) to the client.
If a functional specification “describes how a product will work entirely from the user's perspective. It doesn't care how the thing is implemented. It talks about features.“. Then does anyone see any problem with using User Stories to define a functional specification for a website? Does anyone actually do functional specifications in this way?
Really I am trying to up my game a little, and wondering if this would approach would work for larger clients who perhaps have more stringent ideas on what a functional specification should contain, whereby a formal approach may be required. Definitely at the moment our clients respond well to our method of producing documentation.
I am interested in hearing what people who do project management professionally think about this.
I'm at odds with what a couple of other people have said.
First up the bit I agree with - stories are a great way of stating functional requirements. For my money they're one of the best ways of actually communicating requirements in a way end users will really take in. I've seen too many specs that get signed off without ever having been read.
The one thing I would say you might want to append to them is non-functional requirements - covering performance, security, data volumes, audit, archive and so on. While they can be covered in stories, sometimes they're better covered in a way that crosses all stories.
In terms of whether it's suitable for large companies this is where I disagree. In my experience (and I've done projects for Shell, American Express, a couple of multi-national banks and others) they're often no more formal than smaller companies so they'll be fine with stories. The reality is that a user in a large company is no better equiped (or interested) in reading class and sequence diagrams than they are elsewhere.
The size and complexity of the project may require more detailed requirements but it's the size of the project, not the size of the company that matters when you're determining how you document requirements.
For me the best requirements documentation is documentation that's suited to it's audience, and for me user stories hit the nail on the head most of the time - they're short enough and clear enough that when they sign them off they mean something because they've read and understood them (as opposed to the sign off of a 100 page spec which invariably means they haven't really read it), but good enough for the developers to work from too.
Yes, you can use user stories for your functional requires. I do it all the time, and have been for years. In my opinion, it works really well, and better than other systems I have used.
Would this approach work for larger clients? To make a gross generalization, no. They are going to have some system that use to define requirements, and likely its not user stories. If you come in with user stories, there is going to be a disconnect with the current practices, which you will have to work through.
I have been successful using user stories with larger organizations, but it take a concerted effort, which both parties need to be committed to.
What you're describing are the use-case scenarios that define the features, this is what is required from a usability perspective and is exactly what the client will understand and agree to. Screen mockups and flow diagrams will definately help both the client and developers.
An implementation specification may then be required to instruct developers on what needs to be included in the actual construction, the depth of this will be determined by your developers capabilities that include their knowledge of the house architecture/framework and methodologies/conventions and may include specifics on what impacts various parts of the application.
We also work in small teams (sometimes one or two developers) and believe the above is all that's required in this instance.
Larger companies with much larger teams may use Modeling Software, UML diagrams and other more detailed specifications. In the case where you the primary developer, you should still spend the time designing your application, but if nobody is going to review the designs and insist on all the formalities, your time is better spend implementing the software.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 3 years ago.
Improve this question
Are there any programming methodologies that take into account the concept that the first round of written code is likely to be not what you want to use? The most common thing I hear at the end of a project from a developer is 'If I could do that again, I'd do it so differently.' This is almost an exact mirror of the process a writer goes through after writing a first draft. The difference seems to be that writers then rewrite and rewrite again until they're ready to move into the editing stage, whereas developers seem to write and then refine their first draft with testing and refactoring.
I'm certainly no fan of trying to use alternative analogies to define the development process, but I do think there's value in recognising that your first draft is just to get ideas down, you need further rewrites in order to produce something worthwhile. I just don't think I've ever encountered a programming process or project methodology that recognises that, so I was hoping that the vast collective concious of Stackoverflow might have an idea of where I might start exploring this possibility?
Prototyping seems to address the problem in some way. The wikipedia article on Prototyping names an approach called 'Throwaway prototyping' which seems inline with your way of thinking.
What you are describing is called throwaway prototyping. The idea is that as soon as you have your preliminary requirements, you create a basic model of the system to show the user and/or customer what the final system might look like and how it might function (although there's no real functionality). The user provides feedback on this prototype.
If you wanted to utilize throwaway prototyping, my first suggestion would be to start looking at the spiral process model. However, I'm not familiar with very many methodologies that explicitly utilize throwaway prototyping. The more "agile" methodologies favor evolutionary prototyping or incremental prototyping. The only time I've ever personally used throwaway prototyping was to only prototype the user interface, as the underlying system was already under development and I used whiteboards and pen and paper for the prototypes.
Besides, this is one of Brooks's ideas which he himself found not the most effective after some revision: you've probably heard of "throwing away two systems after planning to throw away just one". Fortunately many such troubles can be overcome nowadays thanks to agile methodologies.
This is exactly the argument that Bruce Eckel is making here.
I would argue that the best thing to do is modularize very well. For example, if you're writing a kernel, the "Get the next available free memory frame" function should reside in its own function. That way, when you figure out that it's written in a really crappy way, you simple erase (of course you're using version control) and start from scratch. That way, your existing modules exist as a way to test your new code.
Going from start to finish and then start to finish again is an awesome way of going through a large percentage of the same bugs again.
Closed. This question is off-topic. It is not currently accepting answers.
Want to improve this question? Update the question so it's on-topic for Stack Overflow.
Closed 12 years ago.
Improve this question
What are the best practices when managing a software project involving a non-English-speaking client?
What communication issues are relevant? Would you maintain documentation in both languages (especially updating the specifications regularly)?
The basic risk in such type of projects is miscommunication, so the top priority is
validating the understanding of both parties, i.e. you should not only validate that the customer understand what you say - you must also validate that you understand what the customer says. Then, with the explicit goal of validating communications and based on the resources you have to understand your customer's language and the resources your customer has to understand your language, you and your customer shall agree on how to handle communications for the project: documentation in both languages, single points of contact, written minutes of all communications, translation of all communications, etc.
To minimize the possibility of misunderstandings, it is better to have all official communications in just one language, if possible. If communications shall be held in more than one language, you must minimize the number of communication channels, i.e. you must not have everybody communicating with everybody else: liaisons should be designated to handle all communications. Single points of contact with known proficiency on the language(s) used in the project are crucial.
Casual communications shall be avoided. All conference calls and meetings shall have written minutes describing all agreements and action items - if multiple languages are being used, all minutes shall be translated by a single party and reviewed by the single point(s) of contact.
The practices I have just described, may seem an ugly burden to bear, but they will prevent a lot of headaches.
Good luck!
My native language is not English, so I'm on the other side. There were times when we had to write project documents in 4-6 languages.
Try to find somebody who understand English (like a key person). I try to avoid the communication in different languages on a project. Of course you can talk and write on different languages with project members, but if you talk or write to all members of the project at once, it should be one language.
Documentation should be maintained in as many languages as many involved. All documents should be updated on a regular basis and try to avoid the situation when you have to tell them that "the English is the current one". Find someone who is native in the target language and translate from English for you. It will be far more better, understandable, and more native than if you try the other way around.
This might be the perfect case in which you might want to switch over to Agile development. This puts less of an emphasis on large amounts of documents and you can provide work at the end of every interval for the customer to sign off on. If you don't know what Agile is, just google it, you'll get tons of information back.
Always follow up with a written confirmation of any verbal discussion. Most people can read foreign languages better then they can speak them. It also helps to pick one language as the standard for all documents and code.
Closed. This question is off-topic. It is not currently accepting answers.
Want to improve this question? Update the question so it's on-topic for Stack Overflow.
Closed 9 years ago.
Improve this question
Probably an easy one:
Are there any rules of thumb or pointers that could help recognise political requirements?
Let’s say one of stakeholders (your boss, a head of another department or an actual user) asks for a feature or particular characteristic of software being developed by yourself or your team. Is there a litmus test to determine whether requirement is political?
This question is really simple and is not about how to deal with political requirements or whether they are bad or good for software. How do you tell that whatever you have been asked to do is to pursue someone’s tacit or actually openly stated political agenda?
Will it really help you to know? I mean - if you're already embroiled in political games you'll know anyway. If you're not it isn't something you'll be able to use.
If you're going to have to implement the feature anyway I'd say just get on with it. Finding out that it's part of some management game will only demotivate you.
That said - if you're working on the sort of application that's so themware that you can't tell whether it's a real user feature or a political lever of some sort then it's probably a safe assumption that everything is political.
I would say that you should assume that all requirements are political.
If you are in a situation where more than one person is responsible for determining the set of features you implement, then every feature is effectively a negotiation between those people. That negotiation makes those features political.
However, even if there is only person deciding what features ship, there is still a pretty strong chance that those decisions are political. In any organization of reasonable size (say more than ten people), you are going to have politics. The politics in that situation will differ than the "design by committee situation". They will focus on currying the favor of the person who decides which features ship, rather than on "if you support my feature, I'll support yours" that exists in the committee scenario. That process, however, is still political.
I'm not trying to say that it's not possible to have a development environment free of politics. It is. However, I would say that to pull of it off that you need:
A small, tightly knit team
A boss that focuses on creating an environment that fosters creativity, and delegating creative ownership, rather than focusing on control over the creative process.
Smart, highly talented and creative people that share a strong sense of purpose and aesthetic values.
Missing any one of those things, you are doomed to a repetitive deluge of office politics.
The best idea is to find out what all the features are to be used for, i.e. find out not only how a feature is to be implemented, but also learn why it should be done. It really helps to know the background of the desired solution. It might even allow you to suggest an alternate feature set that might better suit your customer (maybe even play your own political game).
As long as there is anything you do not understand, do not do the project. It will only cause problems at some point.
Obviously it's a tricky question and much depends on your definition of the 'political'.
I would start with the simple question:
* Are the authors/originators of the requirement really using the software in question?
The requirement could come from your boss but it could be a translated valid requirement of the real user
Here are some I've seen:
It directly contradicts other requirements
It is clearly not feasible technically
It is "out in left field" ... it doesn't fit into the defined problem space
It contradicts common sense
BEWARE ... sometimes this results from your use-cases being wrong or incomplete. I've also purposely allowed some of these to proceed to development (e.g Eye-candy that sells the product but is useless or at least generally not used by the operators).
Use the SCRUM approach. Don't describe a feature as
"It should be doing this and that in the following way"
While the sentence above describes all you need to know to implement the feature, it does not justify the feature. My SCRUM book says features should be written down as a story. A story looks like this:
"As a <user-role>
I need a <functionality>
So that I get <business value>"
A feature that cannot be justified using such a story is an unjustified feature and thus there is no use to actually implement it.
E.g.
"As a visitor of a web portal I need a way to authenticate, so I can access my customer data, but nobody else can"
Now you don't only know that you need an authentication for your web portal, you also know who needs it (the visitors, basically everyone planing on using it more intensively) and you also know why it is needed, as it gives the user some value.
Other examples:
"As a passenger I need a list of all my booked journeys, so that I know when I'm going to travel where and won't lose the overview"
"As a book keeper, I'd like to have the sales tax being automatically printed to each bill based on customer data, so that I don't have to enter it manually each time I'm printing a bill"
If every feature needs to be written like that, you'll automatically see if a feature is for the customer, because it is really necessary, or just something your boss/company wants to have and also why they want to have it (what is the big picture behind it? Why are they doing it?).
The use of ambiguous words or phrases is often political.
However,
Never attribute to malice that which is adequately explained by stupidity.