Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 7 years ago.
Improve this question
How to successfully implement democratic (non-BDFL controlled) type of management for the open source project?
More specifically - for the project using distributed source repositories.
What style of communication is best to adopt in such environment?
How to encourage merging branches into the master?
I am mostly interested in establishing the situation where people can directly merge into the master branch under the "social contract" agreement that they follow the project roadmap (which they themselves help to define) and that code they commit is tested.
I specifically want to encourage workflow
define the problem->define requirements and specific metrics of success->architect->build and test
The reason is that - I often see emails like here is the problem and here is how I think it should be solved
Immediately somebody else jumps in and starts a fight.
Not productive at all.
Often disagreement of that kind stems from not being on the same page on the problem definition, requirements or architecture. Or sometimes just because nobody even thought about such things.
How to encourage people to analyze the problem properly, share great ideas and select the best solutions?
How to organize communication so to avoid silly fights, make good decisions without being overly bureaucratic and move along at a good pace ?
Would you have any suggestions? Are there examples of projects managed this way?
How do you think adoption of distributed revision control instead of centralized affects the style of project management?
edit: found some interesting links in related questions
http://gettingreal.37signals.com/toc.php
http://www.catb.org/~esr/writings/cathedral-bazaar/cathedral-bazaar/
Sorry for this somewhat off-topic answer (i.e. one not addressing directly the question). Please edit at your heart's delight!
Projects _do_ need executive governance!
Such may come from a single Benevolent (or not) Dictator, or a [IMHO, small] group, possibly open, of diverse but like-minded individuals. A standard joke on this is that: "The group should be made of an odd number of members, and 3 is already too many"; in truth, small collegial committees can be very effective.
This requirement for a "non fully democratic" decision making entity is however somewhat aligned with the processes suggested in the question. To effectively harness the good will of contributors to the project, the executive team needs to
be perceived as legitimate
communicate effectively
empower "the masses" to contribute with roadmap definition, problem identification, solution scoping and all other design-level tasks. (All the while it remaining clear that in the end, and after all has been said, final decision will be done in committee.
DELIVER a good and vibrant product (BTW by adopting agile development processes, the time between deliveries is lessened)
compromise when needed
advocate the interest of pooling resources in a coordinated fashion, rather than branching out.
Share the glory!
To support all of this formal documentation and processes are very useful. For example, the define the problem->define requirements and specific metrics of success->architect->build procedure indicated in the question can be implemented in the form a single collaboratively edited document (wiki-based or other), i.e. one per issue/idea. This document is templated with a defined format: required attributes such as date, initial posting info... and sections which are opened (and closed) for editing following a given schedule. This allows keeping a clean(er) record of the way the collective though of a given issue, what was suggested etc, what was [authoritatively] decided and why.
With such a process, the community feels engaged and hopefully individuals not too disappointed when the eventual decisions do not go "their" way. They can read and comment on the what and why of the decisions.
Another useful approach is to reward effective participation by informally (or factually) provide more weight to the contributors who effectively help with the project. The more active members can either gain their way into the "inner circle" or be handed-out leadership roles on subsets of the project.
Finally, the leaders of a project (whether in the context of a "democratic" or of a "partially dicatorial" leadership) need to be ever vigilant about "peace keeping". Contributors to Open Source projects are typically energetic, smart and opinionated individuals; conflict of opinion, conflict of personalities, impatience etc. is to be expected. These clashes however can be eased by systematically addressing issues with clear facts, moderating/editing aggressively against name calling and non-productive forms etc.
Originally posted on MetaOptimize.
Constitution for Governance of Open-Source Projects (v20100227)
Let it be affirmed that the primary goal in instituting governance of an open-source project be to ensure the long-term health of the project.
Accordingly, the default bias should be towards openness and inclusiveness.
However, policy should be changed as issues present themselves, in order to maintain the long-term health of the project.
For the model of decision making, we favor a "do-ocracy".
The people who contribute the most generally command the respect of the community.
Alienating them is the best way to derail the project.
The repository should be open the committers, given that commits can easily be reverted and commit-access easily revoked. This is preferable to alienating potential committers.
To ensure transparency for developers new and old, and allow them to decide their involvement in a project based upon the history of the project, their should be transparency and openess in the inner working of the project. For example, the email archive should be public.
Lastly, let us remember that too much red-tape gets in the way of progress. So red-tape and other barriers to contribution should be avoided, and only added as issues present themselves.
This Constitution can and should be amended as issues present themselves.
Therefore be it resolved.
access to repository
there are several options ranging from one controlling committer to anyone can commit - but upon social agreement that they respect the project guidelines and the roadmap.
in my opinion distributed repository allows you to be more relaxed with who you allow to commit, because there are multiple backups and the repo becomes virtually unbreakable.
on a separate note - anyone can commit approach - which I would like to test out - sounds more like a "wiki". I can directly compare this with my experience managing a wiki (nmrwiki.org): where despite complete openness - where not even user registration is required to edit the resource, people are often wary about "breaking stuff" and this worry becomes a mental barrier to making a contribution. So a permissive approach to repository management may just work.
Communication style:
email and mailing lists:
discuss everything concerning the project in public (?)
when asking questions - do not bundle
questions with your own opinions
encourage people to propose more than one solution
ask people to weigh pros and cons
be brief and to the point
avoid frivolous language that can be perceived negatively with people that do not know you well
Related
Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 7 years ago.
Improve this question
I am building a 'software as a service' website that will be charging users a small monthly fee. I am considering changing the Github repository over from Private to Public. Essentially open sourcing it. Is this suicide? I would like the community to be able to benefit from the code. It is unlikely that I will accept any push request so I'm not going to gain anything in that regard. It is community based, so I think most of the value would be lost by someone self hosting it. It is for a very niche audience so I doubt someone else will start a competing hosting. I would really like the code to be in the open, but not at the expense of my idea of course. How does everyone else feel about this? What is common practice?
Conclusion, I'm keeping it closed for the time being. I may look to open source sometime after launch however.
Since you are not going to accept pushes you might as well hold on get your code stable and then publish it for others to learn and benefit from. You are still building the service, so its not going to attract too many eyeballs either.
From a business point of you, you might want to have a reasonable community around your service before you opensource it. if you are still budding who knows if its taken up by a stronger competitor. If your idea is patented its a different story.
To be honest, and this is not likely going to be a popular answer, but to myself, I would keep it closed for a period of time.
The reasons for this are simple, establish your foothold in the marketplace, build your userbase, your brand, then it gives you a mechanism to market your product further by selectively or completely open sourcing components of your system.
I say do it for both personal benefit and potential strategic benefit ... afterall, alot of software IS a service
Most open-source projects stand to provide a return in the right circumstances. Don't forget, unless you have a patent or some massive advance that is so complex and unfathomable that nobody can re-implement it .. if they want to they will anyway, so you have little protection staying closed source anyway ... even more interesting is that the open-source equivalent may well overtake your proprietary one if it garners support.
People may send you great ideas you never thought of, or take your codebase in a direction you would not have predicted. Unless you have significant value in terms of IP or strategic position tied up in the source code ... releasing it will probably do more good than harm.
Also, by being first to the open-source arena with your code, you gain control over any resulting community driven development ... if somone reimplemented your functionality and went open source ... could you compete on any front?
I know it is a cliche, but probably for good reason, but read The Cathedral and the Bazaar and the essay Open Source as a Signalling Device - An Economic Analysis which is an interesting read. Michael E. Porter's texts on competition analysis are interesting when held up against the mixed value economics and competitive forces of open source and shows how disruptive open-sourcing a product can be to competitors ... and how it can add value to your market position. Also, whilst counterintuative, it can raise the barriers to a successful entry by competitors.
More food for thought on the advantages and disadvantages of open sourcing:
What the DoD thinks of open source
Alfred H. Essa "Innovation and strategic advantage: lessons from open source" (warning, journal link)
I like to fix flaws wherever I see them, and perhaps I am one of your users. I'd rather send a patch than send a potentially nagging-sounding email any day.
What benefit are you hoping to gain from making the code open source? If you don't want the input of other developers then there are very few advantages and a whole lot of potential disadvantages.
Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 7 years ago.
Improve this question
Some time ago I observed a few people trying to start an open source project. About a week after the project started it more or less completely dissolved, partly due to issues with how the project itself was managed.
The ideas behind the project were however very well thought and a lot of people are still interested in seeing it realized. So far no one have made any serious attempt to recreate it but a few of us are thinking about doing so. Of course we don't want the project to end the same way it did last time.
Now to my question. How should one start a successful open source project, where successful is defined as "the project does not die unless no one is no longer interested in the software itself anymore?"
Nice question, though it's more worthy of a book than a simple article, IMHO. And I hope it comes as no surprise that most of the best advice is social, not technical.
Here are some observations in no particular order:
Don't make a big infrastructure investment up front Unless you're already an Apache committer (or somesuch), don't shop around for a sponsoring organization or host your own servers, etc. Get up on GitHub in 5 minutes and don't look back. Put your energy in features.
Lower the barrier for entry Don't make potential contributors jump through hoops or undergo a background check before you'll listen to their ideas. Open source projects are networked economies... you need the energy of others. Even misguided activity is better than no activity on your project. You can always steer the codebase in a better direction later.
Minimize custom code Don't write a custom logging tool or XML parsing API... there are open source implementations that are (1) good enough, (2) better maintained, and (3) better than yours will become anyway. The more energy you can focus on your core problem, the better.
Live on the edge People and organizations will only invest in improving your project if they will directly benefit. Eat your own dogfood. Create dependencies in your other projects (like with your employer) on your open source project, even if it isn't "perfect" yet. (Hint: software projects are never perfect, they're either works-in-progress or dead.)
GitHub is a good place because it makes it easy for someone with even just a little bit of interest to fork your project and apply his/her patches to share with others.
But it's really about the attitudes around your project more than where you host it or other simple considerations like that. Be benevolent, serious, and judicious, keep a community going even though it will be pretty small for a while, and so on. Accept patches that should be accepted, reject patches that should be rejected. Just be a good person, developer, and manager, and apply those skills to your project, and it should be fine.
You are saying it yourself. The most important thing is that it should have people who care enough about it to deal with the problems instead of abandoning.
If no one cares enough, it will die again. Try a different project where you do care enough.
"A lot of people interested in seeing it realized" means nothing if nobody will actually do the work, fight the fights and stay put.
I don't think it's set in stone, but for me the biggest point is that your project should fill a gap in the existing ecosystem. In other words, there has to a space for your project to live.
Other than that, I can say that the best way to stay motivated is to work together with people. You say that there are still a lot of people interesting in seeing it realized. So, why don't those people do something about it? Surely they can do something. I think a common misconception is that contributing to an open-source project means you have to be able to write code.
There's more to it:
Write documentation
Create graphical elements
Discuss features and roadmaps
promote the project
etc. etc.
Sure, not all of these points are applicable to every project, but trying to get people to commit to a project will eventually help you and/or your projectmembers to stay commited as well. You don't want to let down all the other folks on the project, do you? ;-)
This is kind of off-topic on SO, but I'll bite anyway.
Most FOSS projects are started by a SINGLE person. Other people come on board after this person has produced some code that does something vaguely useful. So if you want to start a project, do it yourself, set up a site on something like Google Code, and write some code. The last is the most important.
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 8 years ago.
Improve this question
Contributing to open source can have many forms: working with issue trackers, patches, further development, documenting, funding, etc. Assuming your company uses open source projects, what is the single most important reason why you're not contributing back to the community?
Developers cost us money. Open source does not cost us money. Hence, if we start giving developers time to work on open source software then open source loses its competitive advantage and we may as well give MS a call since at least we can define how much money they cost us upfront.
We do, we're founded on Open Source - but I guess we're special ;)
Anyway, this is not like a true answer to your question, but rather an answer to the "questions" in the other answers I guess. There are many ways to contribute to Open Source. Sure you can contribute code, but the other thing you can contribute is money by donating. Jeff Atwood (one of the founders of SO) did this a couple of months ago to a wiki system system I know.
When I worked for my previous startup we gave WatiN $300. This is a contribution, and probably a both a better (and at least cheaper) contribution then having one of our coders trying to figure out the code model and coding standard etc behind WatiN and then fix some bug and supply a patch.
But the THIRD way to "contribute" to your favorite Open Source project is more subtle, but often the definitive best way you can contribute which is by giving it attention like I just did with WatiN through that link.
I am willing to be $100 on that someone reading this answer will check out the link to WatiN, read about the project and download it and start using it in their own test suites. And they should since WatiN is a great Open Source project and Jeroen the guy behind it is truly helpful!
That is also contributing. Helping your favorite Open Source project get some attention by telling others how great it is!
We do contribute back to open source in the one situation where it would be pure insanity not to. When we fix bugs, we always ensure that they are pushed upstream.
As I say, it would be really insane to not do that, and have the alternative of maintaining a fork.
Our management doesn't understand open source. I'm not sure that our boss understands that we are using OSS for development.
In the last time, our boss wanted to release some stuff as open source, but the package should be bundled with a support-contract, so I don't believe he really knows what Open-Source means.
So in one sentence: we don't give back to open source because our management doesn't understand the concept behind open source.
Update: Now we have an OS-product, but our management do not understand it until today. Actually we did it, because some of our customers talked about open-source (and really meant for free).
We contribute back patches and bugfixes.
We don't generally start new projects, though. We don't really have the overhead to support such a project. Unfortunately, you can't just post a tarball on a website and expect strangers to add features to your code. It takes work to build a community.
Developer time/team resources, and the "appropriateness" of contributing code back.
Meaning that, if we make modifications to an OSS project, sometimes the changes aren't necessarily appropriate to contribute back to the project. This may be because of IP rights, but actually, the most common reason is that we simply don't anticipate that other people would require such specific modifications to the software in the way that we've made it. So generally speaking, such patches don't make sense to send back to the team developing the OSS project.
In other cases, these changes could be sent as a patch to the OSS project developers, but this would require cleaning up/reformatting the code, separating out private company data from the patch, etc. Usually, if we're using OSS software in the beginning, we don't care about such things, because most OSS software is somewhat dirty in terms of code quality anyways (ie, no test cases, coding standards, documentation, etc.). Therefore, the time required to clean up our dirty fixes to already dirty code is usually more time than we want to spend for the altruism factor here.
That said, I have worked at companies that did contribute back to OSS projects when necessary, and those that did not made monetary contributions to some OSS projects or distributions.
In my opinion the biggest problem is that most companies are doing development for projects. If a project develops something that is worthwhile to be published as open source the commitment for maintenance can only be given till the project is finished. After that no more resources are available for further developments, support of the community, bug fixes etc. This usually means a slow death for the open source "product".
Also, some companies are very eager to look at the PR for things they publish, and this usually means to go through all the processes for publications. This is something which in general overwhelms engineers and programmers.
Getting it through legal. Seriously, even as a huge contributer to open source software, as a large company the bureaucracy is a killer. (Hope Legal don't read this:)
The company I work for produces software that is proprietary and our software is highly specialized and is our major competitive advantage over all the other companies in our industry. Can't imagine why Open Source isn't something we encourage.
What about a company that doesn't have developers? Maybe they're not a software group, and are using OSS to save money, a la a web-based group that uses LAMP, but never modifies any of the components?
In our case, we produce extremely customized software for the specific circumstances of a state office. Because of that, our software has no utility for anyone else. Being a state office, we aren't at liberty to "donate" time or money, either.
In theory, we could open-source some of our documentation, but again a lack of demand would make it nothing more than an empty gesture.
Business logic.
If I start building a project where I use the source code for a FLOSS project rather than just a library then I need to develop with an awareness of two factors: the changes to the code to make it do what I want and those aspects that I would be allowed to release to the world.
Generally it's not that difficult to do this, but if deadlines are tight then I'm not going to 'waste' time stripping out our proprietary extensions.
Programmers cost us money, but contributing to open source doesn't generate a cent of revenue.
We do contribute and are very proud of it !
http://hg.nuxeo.org/opensocial is all about our contribution to Nuxeo from Leroy Merlin.
Ok, i doesn't generate a cent of revenue, but it doesn't really costs more. And when people will contribute to our code (patches, bug fixes, extension), this will be code that will cost us nothing.
Moreover, our contribution is now included in the core feature of Nuxeo, so now we will benefit of a vendor certified integration of our code.
I am not sure contributing with money is the best way to help OpenSource software. When Jeff Atwood gave some $5000 to an OpenSource project the lead of the project was grateful... but if I recall correctly he was not too sure about what to do with it.
Developers who contribute to OpenSource projects are not paid to do so. They do it because they like it, want to prove something to themselves, etc... but money is never the cause since they know that they won't probably earn a dime. At best, they might attract attention which may then generate revenues (think new employer, more traffic to their blog, etc...)
Now, I don't say that one should not contribute, but I think that monetary contributions are not as efficient as one might think, companies have a tendency to think that their model (capitalist) naturally extend to everything around them :/
In my opinion, an OpenSource project benefit more from patches/bug reports than from direct monetary contribution, exceptions being hosting the website / repository of the project or financing meetings for the top contributors so that they can discuss face to face when the need arise, but though this cost money, this is not directly giving money.
Even though we do give back to open source as code patches, and releasing open source software I can understand why other companies don't. Because "it doesn't make any profit" :)
Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 8 years ago.
Improve this question
We have a series of closed source applications and libraries, for which we think it would make sense opening up the source code.
What has been blocking us, so far, is the effort needed to clean up the code base and documenting the source before opening up.
We want to open up the source only if we have a reasonable chance of the projects being successful -- i.e. having contributors. We are convinced that the code would be interesting to a large base of developers.
Which factors, excluding the "interestingness" and "usefulness" of the project, determine the success of an open source project?
Examples:
Cleanliness of code
Availability of source code comments
Fully or partially documented APIs
Choice of license (GPL vs. LGPL vs. BSD, etc...)
Choice of public repository
Investment in a public website
There are a several things which dominate the successfulness of code. All of these must be achieved for the slightest chance of adoption.
Market - There must be a market for your open source project. If your project is a orange juicer in space, I doubt that you'll be very successful. You must make sure your project gets a large adoption amongst users and developers. It is twice as likely to succeed if you can get other corporations to adopt it as well.
Documentation - As you touched on earlier documentation is key. Amongst this documentation is commented code, architectural decisions, and API notes. Even if your documentation contains bugs, or bugs about your software it is ok. Remember, transparency is key.
Freedom - You must allow your code to be "free" - by this I mean free as in speech, not as in beer. If you have a feeling your market is being a library for other corporations a BSD license is optimal. If your piece of software is going to run on desktops then GPL is your choice.
Transparency - You must write software in a transparent environment. Once you go open source there is no hidden secrets. You must explain everything you do, and what you are doing. This will piss off developers like no other
Developer Community - A strong developer community is required. This must be existing. Only about 5% of users contribute back to the project. If someone notices there haven't been any releases for a year they wont think "Wow, this piece of software is done," they will think "developers must of dumped it." Keep your developers working on it, even if it means they are costing you money.
Communications - You must make sure you community is able to communicate. They must be able to file bugs, discuss workarounds, and publish patches. Without feedback, it is pointless to opensource the project
Availability - Making your code easy to get is necessary, even if it means pissing off lawyers. You have to make sure your project is easy to download, and utilize. You don't want the user to have to jump through 18 nag screens and sign a contract in order to do this. You have to make things simple, and clean
I think that the single most important factor is the number of users that are using your project.
Otherwise its just a really well written, usefull and well documented bunch of stuff that sits on a server not doing very much...
To acquire contributors, you first need users, then you need some incompleteness. You need to trigger the "This is cool, but I really wish it had this or was different in this way." If you are missing an obvious feature, it's extremely likely a user will become a contributor to add it.
The most important thing is that the program be good. If its not good, nobody will use it. You cannot hope that the chicken-and-egg will reverse and that people will take it for granted until it becomes good.
Of course, "good" merely means "better than any other practical option for a significant number of people," it doesn't mean that its strictly the best, only that it has some features that make it, for many people, better than other options. Sometimes the program has no equivalent anywhere else, in which case there's almost no requirement in this regard.
When a program is good, people will use it. Obviously, it has to have a market among users--a good program that does something nobody wants isn't really good no matter how well its designed. One could make a point about marketing, but truly good products, up to a point, have a tendency to market themselves. Its much harder to promote something that isn't good, so clearly one's first priority should be the product itself, not promoting the product.
The real question then is--how do you make it good? And the answer to that is a dedicated, skilled development team. One person can rarely create a good product on their own; even if they're far better than the other developers, multiple perspectives has an incredibly useful effect on the project. This is why having corporate sponsors is so useful--it puts other developers' (from the corporation) minds on the problem to give their own opinion. This is especially useful in the case that developing the program requires significant expertise that isn't commonly available in the community.
Of course, I'm saying this all from experience. I'm one of the main developers on x264 (currently the most active one), one of the most popular video encoders. We have two main developers, various minor developers in the community that contribute patches, and corporate sponsorship from Joost (Gabriel Bouvigne, who maintains ratecontrol algorithms), from Avail Media (who I work for sometimes on contract and who are currently hiring coders on contract to add MBAFF interlacing support), and from a few others that pop up from time to time.
One good developer doesn't make a project--many good developers do. And the end result of this is a program that encodes video faster and at a far better quality than most commercial competitors, hardware or software, even those with utterly enormous development budgets.
In looking at these issues you might be interested in checking out the online version of a course on open source at UC Berkeley, called Open Source Development and Distribution of Digital Information: Technical, Economic, Social, and Legal Perspectives. It’s co-taught by Mitch Kapur (Lotus founder) and Paula Samuelson, a law school professor. I have a long commute and put the audio of the course on my iPod last year – they talk a lot about what works, what doesn’t and why, from a very broad (though obviously academic) perspective.
Books have been written on the subject. In fact, you can find a free book here: producing open source software
Really, I think the answer is 'how you run the project'.
All of your examples matter, yes, but the key things are how the interaction between developers is managed, how patches etc are handled/accepted, who's 'in charge' and how they handle that responsibility, and so on and so forth.
Compare and contrast (the history isn't hard to track down!) the management of the development of Class::DBI and DBIx::Class in Perl.
I was just reading tonight an excellent post on the usability aspect of successful vs unsuccessful open source projects.
Excerpt:
A lot of bandwidth has been wasted arguing over the lack of usability in open-source software/free software (henceforth “OSS”). The debate continues at this moment on blogs, forums, and Slashdot comment threads. Some people say that bad usability is endemic to the entire OSS world, while others say that OSS usability is great but that the real problem is the closed-minded users who expect every program to clone Microsoft. Some people contend that UI problems are temporary growing pains, while others say that the OSS development model systematically produces bad UI. Some people even argue that the GPL indirectly rewards software that’s difficult to use! (For the record, I disagree.)
http://humanized.com/weblog/2007/10/05/make_oss_humane/
Just open-source it. Most probably, nobody will start contributing yet. But at least you can write on the press-releases that your product is GPL or whatever.
The first step is that people start using it...
And maybe then, after users get comfortable, they will start contributing.
Everyone's answers have been good so far, but there's one thing missing and that's good oversight. Nothing kills an open source project faster than not having some sort of project management. Not to tell people what to do so much as to just add some structure and tasking for the developers you are hoping to attract.
Disorganized projects fall apart fast. It's not a bird you just let go and watch it fly away.
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
In the course of your software development lifecycle, what essential design artifacts do you produce? What makes them essential to your practice?
The project I'm currently on has been in production for 8+ years. This web application has been actively enhanced and maintained over that time. While we have CMMI based policies and processes in place, with portions of our practice being well defined, the design phase has been largely overlooked. Best practices, anyone?
Having worked on a lot of waterfall projects in the past and a lot of adhoc and agile projects more recently, there's a number of design artifacts I like to create although I can't state enough that it really depends on the details of the project (methodology/team structure/timescale/tools etc).
For a generic, server-based 'enterprise application' I'd want the bare minimum to be something along these lines:
A detailed functional design document (aka spec). Generally something along the lines of Joel s' WhatsTimeIsIt example spec, although probably with some UML use-case diagrams.
A software techical design document. Not necessarily detailed for 100% system coverage but detailed in all the key areas and containing all the design decisions. Being a bit of an UML freak it'd be nice to see lots of pictures along the lines of package diagrams, component diagrams, key feature class diagrams, and probably some sequence diagrams thrown in for good measure.
An infrastructure design document. Probably with UML deployment diagram for the conceptual deisng and perhaps a network diagram for something more physical.
When I say document any of the above might be broken down into multiple documents, or perhaps stored on a wiki/some other tool.
As for their usefulness, my philosophy has always been that a development team should always be able to hand over an application to a support team without having to hand over their phone numbers. If the design artifacts don't clealry indicate what the application does, how it does it, and where it does it then you know the support team are going to give the app the same care and attention they would a rabid dog.
I should mention I'm not vindicating the practice of handing software over from a dev team to a support team once it's finished, which raises all manner of interesting issues, I'm just saying it should be possible if the management so desired.
Working code...and whiteboard drawings.
:P
Designs change so much during development and afterwards that most of my carefully crafted documents rot away in source control and become almost more of a hindrance than a help, once code is in production. I see design documents as necessary to good communication and to clarify your thinking while you develop something, but after that it takes a herculean effort to keep them properly maintained.
I do take pictures of whiteboards and save the JPEGs to source control. Those are some of my best design docs!
In our model (which is fairly specific to business process applications) the design artefacts include:
a domain data model, with comments on each entity and attribute
a properties file listing all the modify and create triggers on each entity, calculated attributes, validators and other business logic
a set of screen definitions (view model)
However do these really count as design artefacts? Our framework is such that these definitions are used to generate the actual code of the system, so maybe they go beyond design.
But the fact that they serve double duty is powerful because they are, by definition, up to date and synchronised with the code at all times.
This is not a design document, per se, but our unit tests serve the dual purpose of "describing" how the code they test is supposed to function. The nice part about this is that they never get out of date, since our unit tests must pass for our build to succeed.
I don't think anything can take the place of a good old fashioned design spec for the following reasons:
It serves as a means of communicating how you will build an application to others.
It lets you get ideas out of your head so you don't worry about tracking a million things at the same time.
If you have to pause a project and return to it later you're not starting your thought process over again.
I like to see various bits of info in a design spec:
General explanation of your approach to the challenge at hand
How will you monitor your application?
What are the security concerns and how are they addressed?
Flowcharts / sequence diagrams
Open issues
Known limitations
Unit tests, while a fantastic and arguably critical item to include in your application development, don't cover all of these topics.