I have to second that. DocBook can be a pain to get started with and learn, partially because it's soooo flexible and powerful. I probably spent a week getting all of the pieces together (editor, DTDs, Xalan, XSL, etc), but now I find it quite easy to churn out anything from a full reference manual to some simple man pages.
I finally found Morphon's XML Editor and have been quite happy with it for editing DocBook documents (despite the fact that it's currently a beta version that will crash once in a while).
I'm pretty sure Quintus corporation (later purchased by Intergraph) had something which fits the bill. We purchased a license for it in 1992, but I'm pretty sure we weren't the first customers. I think the architecture was called WorkPro and the app was called CustomerQ or some such thing.
Basically it was a call/bug tracking database. The client wasn't too thin, being written in Object Oriented Prolog w/ X extensions, but it had a remote DB server, an X-based client, and the ability to write application code in either a proprietary language or Prolog.
It was the bane of my existence for several years. Hopefully it helps you more that it did me.
I used to feel the same way about print manuals being always better, but I've found that the more I use on-line docs, the more I'm getting used to it. My guess is that the next generation of kids will grow up reading more and more on the screen and will not feel the same as you do about printed material.
People who were born before 1979 tend to prefer text over charts and pictures while the opposite is true for people born since then (BusWeek 6/3/200). It will interesting to see if the same type of thing happens with printed vs paperless documents.
Very cool to see this. It looks like it would be easier to manufacture than the 'vertical transistor' recently announced.
With all of the advancements in transistor size, you've got to think that wiring the little buggers together is going to get real interesting. Smaller transistors mean less voltage, less drive strength, and lower noise margins. Narrower interconnect means higher resistance. Try to pack the metal lines too close together and you've got even more noise problems.
Aren't we already at the point where the interconnect is beginning to dominate silicon real estate?
I've worked on dozens of s/w projects ranging from solo assignments to enormous multi-headed monsters involving hundreds of people doing coding and validation. I've noticed a method which seems to work fairly well for a variety of project sizes. Of course, YMMV.
1. Don't get tied up in writing a bunch of specs up-front. The spec-it-all-first method almost always results in sub-optimal implementations and reams of out-of-date documentation.
2. Get a handful of senior coders (and one or two customers of the product, if possible) in a room and have them architect a skeleton of the project on the whiteboard. Get a junior coder to take notes. These minutes are your first "design document".
3. Figure out how to partition all of the pieces from #2 into nice libraries and data structure definitions. Define the basic functionality of the libraries without specifying the exact interfaces (which will be wrong for the first two iterations).
4. Prototype and re-prototype the implementation, allowing the developers to work out the interfaces between themselves. Get customers to try out the prototypes.
5. Schedule a "get well" phase of the project where code is cleaned up and interfaces become mostly frozen. This is the ideal time to document the "final" interfaces, data structures, and algorithms. Hold peer reviews of code and documentation. Discipline is vital here if you want a documented design.
6. Productize.
7. Maintenance mode. If you can find a way to keep the documentation up to date from this point on, please let me know how you do it.
While any document which isn't auto-generated directly from the code will become out-of-date, getting most implementation details figured out by trial and error before writing an official document will make it more accurate with less maintenance overhead.
I've seen a lot of projects fail miserably when management spent too much time trying to spec everything up front. One group in my company has an offical flow which goes something like this:
1. Write an Market Requirements Document (MRD)
2. Review the MRD with a lot of people, many of whom have no idea what the market really needs but have a lot of opinions about how the MRD should look.
3. Revise the MRD based on the review.
4. Write an External Product Specification (EPS). This defines every feature which is to go into the product that is visible to the user (as well as how it is visible to the user).
5. Review the EPS with a lot of people.
6. Revise the EPS and get "buy-in" from all of the "stakeholders".
7. Write an Internal Product Specification (IPS). This defines all internal modules and most of the data structures and algorithms. Note that usually this is published before any code has been written.
8. Review the IPS with a lot of people.
9. Revise the IPS until everybody is happy.
10. Start writing code (usually about 4 months after the process has started).
11. Find out that the customer has already started using another product from somebody who has followed the first method above.
12. If the other product is from another group in the same company, try to kill that product via political means.
13. Finish coding up something which is grossly inefficient and doesn't meet the customers' real needs, but that meets most or all of the items in the MRD, EPS, and IPS.
Ok, maybe some of that isn't in the offical methodology...
Finally, there are many factors besides design documentation which help to make or break a project (having talented people seems to be most important); so pick your battles if you're going up against management edict.
Slashdot Mirror
I have to second that. DocBook can be a pain to get started with and learn, partially because it's soooo flexible and powerful. I probably spent a week getting all of the pieces together (editor, DTDs, Xalan, XSL, etc), but now I find it quite easy to churn out anything from a full reference manual to some simple man pages.
I finally found Morphon's XML Editor and have been quite happy with it for editing DocBook documents (despite the fact that it's currently a beta version that will crash once in a while).
I'm pretty sure Quintus corporation (later purchased by Intergraph) had something which fits the bill. We purchased a license for it in 1992, but I'm pretty sure we weren't the first customers. I think the architecture was called WorkPro and the app was called CustomerQ or some such thing.
Basically it was a call/bug tracking database. The client wasn't too thin, being written in Object Oriented Prolog w/ X extensions, but it had a remote DB server, an X-based client, and the ability to write application code in either a proprietary language or Prolog.
It was the bane of my existence for several years. Hopefully it helps you more that it did me.
Oskee-wow-wow,
PlazMan
I used to feel the same way about print manuals being always better, but I've found that the more I use on-line docs, the more I'm getting used to it. My guess is that the next generation of kids will grow up reading more and more on the screen and will not feel the same as you do about printed material.
People who were born before 1979 tend to prefer text over charts and pictures while the opposite is true for people born since then (BusWeek 6/3/200). It will interesting to see if the same type of thing happens with printed vs paperless documents.
Very cool to see this. It looks like it would be easier to manufacture than the 'vertical transistor' recently announced.
With all of the advancements in transistor size, you've got to think that wiring the little buggers together is going to get real interesting. Smaller transistors mean less voltage, less drive strength, and lower noise margins. Narrower interconnect means higher resistance. Try to pack the metal lines too close together and you've got even more noise problems.
Aren't we already at the point where the interconnect is beginning to dominate silicon real estate?
I've worked on dozens of s/w projects ranging from solo assignments to enormous multi-headed monsters involving hundreds of people doing coding and validation. I've noticed a method which seems to work fairly well for a variety of project sizes. Of course, YMMV.
1. Don't get tied up in writing a bunch of specs up-front. The spec-it-all-first method almost always results in sub-optimal implementations and reams of out-of-date documentation.
2. Get a handful of senior coders (and one or two customers of the product, if possible) in a room and have them architect a skeleton of the project on the whiteboard. Get a junior coder to take notes. These minutes are your first "design document".
3. Figure out how to partition all of the pieces from #2 into nice libraries and data structure definitions. Define the basic functionality of the libraries without specifying the exact interfaces (which will be wrong for the first two iterations).
4. Prototype and re-prototype the implementation, allowing the developers to work out the interfaces between themselves. Get customers to try out the prototypes.
5. Schedule a "get well" phase of the project where code is cleaned up and interfaces become mostly frozen. This is the ideal time to document the "final" interfaces, data structures, and algorithms. Hold peer reviews of code and documentation. Discipline is vital here if you want a documented design.
6. Productize.
7. Maintenance mode. If you can find a way to keep the documentation up to date from this point on, please let me know how you do it.
While any document which isn't auto-generated directly from the code will become out-of-date, getting most implementation details figured out by trial and error before writing an official document will make it more accurate with less maintenance overhead.
I've seen a lot of projects fail miserably when management spent too much time trying to spec everything up front. One group in my company has an offical flow which goes something like this:
1. Write an Market Requirements Document (MRD)
2. Review the MRD with a lot of people, many of whom have no idea what the market really needs but have a lot of opinions about how the MRD should look.
3. Revise the MRD based on the review.
4. Write an External Product Specification (EPS). This defines every feature which is to go into the product that is visible to the user (as well as how it is visible to the user).
5. Review the EPS with a lot of people.
6. Revise the EPS and get "buy-in" from all of the
"stakeholders".
7. Write an Internal Product Specification (IPS). This defines all internal modules and most of the data structures and algorithms. Note that usually this is published before any code has been written.
8. Review the IPS with a lot of people.
9. Revise the IPS until everybody is happy.
10. Start writing code (usually about 4 months after the process has started).
11. Find out that the customer has already started using another product from somebody who has followed the first method above.
12. If the other product is from another group in the same company, try to kill that product via political means.
13. Finish coding up something which is grossly inefficient and doesn't meet the customers' real needs, but that meets most or all of the items in the MRD, EPS, and IPS.
Ok, maybe some of that isn't in the offical methodology...
Finally, there are many factors besides design documentation which help to make or break a project (having talented people seems to be most important); so pick your battles if you're going up against management edict.