Any standard for documenting design available?
-
There are so many books/standards on how to document architecture. But I am not aware of any book/standard on how to document (detailed) design. Example: The architect creates on documentation for "OurServerComponent" with all the high-level views according to any standard ( e.g. IEEE1471). But where and how do I have to document the low-level-design of my own 5 classes?
-
There are so many books/standards on how to document architecture. But I am not aware of any book/standard on how to document (detailed) design. Example: The architect creates on documentation for "OurServerComponent" with all the high-level views according to any standard ( e.g. IEEE1471). But where and how do I have to document the low-level-design of my own 5 classes?
Visual Studio class diagram, Rational Rose, UML diagramming tool...not sure if that is what you are after
CodingYoshi Artificial Intelligence is no match for Human Stupidity.
-
Visual Studio class diagram, Rational Rose, UML diagramming tool...not sure if that is what you are after
CodingYoshi Artificial Intelligence is no match for Human Stupidity.
Hi Yosh, no this is not what I'm looking for. I'm looking for some guidance(or standard) on how structure design-documentation in the best way. For architecture there are clear rules available now (IEEE-Standard or beyond-view from SEI). But how and where do I organize/structure the UML diagrams for my 500 classes? My diagrams were intended to be used not by me but by my audience. My colleages put them automatically in the trash, because nobody can see the complete picture from all of my details
-
There are so many books/standards on how to document architecture. But I am not aware of any book/standard on how to document (detailed) design. Example: The architect creates on documentation for "OurServerComponent" with all the high-level views according to any standard ( e.g. IEEE1471). But where and how do I have to document the low-level-design of my own 5 classes?
What CodingYoshi says is right. UML is the standard. You may wish to preface your class diagrams with a component diagram. Then break the classes up accordingly. If you have 500 classes in a single library, this will be a valuable exercise and ask questions about the current design. There are books re documentation. I teach this subject and wrestled with the same question. The answer is there are guides but no standard. Each project is unique, there audiences vary. Documentation needs to be tailored to the project and audience.
"You get that on the big jobs."
-
What CodingYoshi says is right. UML is the standard. You may wish to preface your class diagrams with a component diagram. Then break the classes up accordingly. If you have 500 classes in a single library, this will be a valuable exercise and ask questions about the current design. There are books re documentation. I teach this subject and wrestled with the same question. The answer is there are guides but no standard. Each project is unique, there audiences vary. Documentation needs to be tailored to the project and audience.
"You get that on the big jobs."
Of course, UML is the standard for modelling/diagramming. But it says nothing to the "strategy for documentation-structuring". Hard to explain what I want, let's try with an example: I have written my architectural documentation Ieee1471-compliant, with all the viewpoint, views and the like. But now I have to document 500 classes/lower-level-components. It should not be part of the architecture-document (clearly kept out by ieee-guidance). But where else should I do it? Should I create a document "MyProjectsSwDesign.doc"? And which content/structure does it have. I have so many books on design, but all of them explain how to do single diagrams in the best way, nothing else. A similar topic, but at another area, requirements-engineering/management, is the SRS. Also here -the SRS templates from Ieee -is an international standard/method
-
Of course, UML is the standard for modelling/diagramming. But it says nothing to the "strategy for documentation-structuring". Hard to explain what I want, let's try with an example: I have written my architectural documentation Ieee1471-compliant, with all the viewpoint, views and the like. But now I have to document 500 classes/lower-level-components. It should not be part of the architecture-document (clearly kept out by ieee-guidance). But where else should I do it? Should I create a document "MyProjectsSwDesign.doc"? And which content/structure does it have. I have so many books on design, but all of them explain how to do single diagrams in the best way, nothing else. A similar topic, but at another area, requirements-engineering/management, is the SRS. Also here -the SRS templates from Ieee -is an international standard/method
-
There are so many books/standards on how to document architecture. But I am not aware of any book/standard on how to document (detailed) design. Example: The architect creates on documentation for "OurServerComponent" with all the high-level views according to any standard ( e.g. IEEE1471). But where and how do I have to document the low-level-design of my own 5 classes?
-
I didn't even know about the spec that you originally mentioned. I have always rolled my own process docs.
-
There are so many books/standards on how to document architecture. But I am not aware of any book/standard on how to document (detailed) design. Example: The architect creates on documentation for "OurServerComponent" with all the high-level views according to any standard ( e.g. IEEE1471). But where and how do I have to document the low-level-design of my own 5 classes?
There are some software design practices available, some of them are related to the industry that the applications are designed for, for instance there are specific IEEE standards the apply to medical devices. As for standards specific to documentation I'm not familiar with any standard, as long as the software practices are applied correctly. However a good luanching point would be a site such as the IEE computer society. Here they provide some good information. http://www.computer.org/portal/web/swebok[^] The FDA also provides some guidance as to what should be documented for software requirements and design descriptions. Here is a link to a pdf file from the FDA: General Principles of Software Validation[^] Cheers!
It was broke, so I fixed it.