Documenting Design
-
My job role has changed significantly as we have started offshoring most of our coding. Since I have domain knowledge and good relationships with the client, my responsibilities have been relegated to mostly doing design work. We are getting ready to start a fairly large project and I will be overseeing 3-4 offshore developers. Previously, the company I work for has not placed a lot of emphasis on documenting design other than documenting UI and database design, etc. It is critical that designs now be detailed enough that offshore developers can code new design with minimal oversight. I have two questions: 1) What type of training materials would any of you suggest? Specifically ones that focus on communicating design (all other parts of the SPLC are managed quite well). 2) What tools would you suggest to aid in this process? Thanks in advance, Kevin
-
My job role has changed significantly as we have started offshoring most of our coding. Since I have domain knowledge and good relationships with the client, my responsibilities have been relegated to mostly doing design work. We are getting ready to start a fairly large project and I will be overseeing 3-4 offshore developers. Previously, the company I work for has not placed a lot of emphasis on documenting design other than documenting UI and database design, etc. It is critical that designs now be detailed enough that offshore developers can code new design with minimal oversight. I have two questions: 1) What type of training materials would any of you suggest? Specifically ones that focus on communicating design (all other parts of the SPLC are managed quite well). 2) What tools would you suggest to aid in this process? Thanks in advance, Kevin
I'll suggest that you start off by investing in a decent enterprise architecture tool. This will help you to document sequence diagrams, activity diagrams, etc. When it comes to communicating design, we find the RUP process to be helpful - use cases, detailed designs, storyboards, etc... You may want to read up on RUP to get a better understanding of what you will be producing.
"WPF has many lovers. It's a veritable porn star!" - Josh Smith
-
My job role has changed significantly as we have started offshoring most of our coding. Since I have domain knowledge and good relationships with the client, my responsibilities have been relegated to mostly doing design work. We are getting ready to start a fairly large project and I will be overseeing 3-4 offshore developers. Previously, the company I work for has not placed a lot of emphasis on documenting design other than documenting UI and database design, etc. It is critical that designs now be detailed enough that offshore developers can code new design with minimal oversight. I have two questions: 1) What type of training materials would any of you suggest? Specifically ones that focus on communicating design (all other parts of the SPLC are managed quite well). 2) What tools would you suggest to aid in this process? Thanks in advance, Kevin
Read books on Software Analysis and Design. Some tools which come to mind are Rational Rose, MS Visio, and buy a roll of paper from a meat market (yes the one they use for wrapping meat). You can sketch diagrams using this paper.
-
Read books on Software Analysis and Design. Some tools which come to mind are Rational Rose, MS Visio, and buy a roll of paper from a meat market (yes the one they use for wrapping meat). You can sketch diagrams using this paper.
Thanks for the info. I've been introduced to Rational in the past, but I'd be fighting an uphill battle to obtain licensing for it. We are pretty much limited to Microsoft products. I know that there are a lot of features in Visio that I'm not aware of, so that might be a good starting point. Is there anything in Visual Studio Team System that would be helpful? I've watched some demos on the product and I see that it has static code analysis, profiling, testing support etc, but it doesn't appear that it would be helpful for what I'm looking for. Automatic code generation doesn't work well for us either, since we are dealing with existing c++ applications and we generally don't create a lot of new classes. Drawing stuff out on paper (or a white board) is always a good idea. With this offshore design, we are finding that we need a high level of detail in the design. I think what would be helpful would be able to define classes and their member functions and include pseudo code with the member functions. I'm trying to get away from Microsoft Word. I find my self spending more time fighting Microsoft Word than I do thinking about design. I know Rational has some ability to generate some documentation. I think that alone would boost my productivity considerably.
-
Thanks for the info. I've been introduced to Rational in the past, but I'd be fighting an uphill battle to obtain licensing for it. We are pretty much limited to Microsoft products. I know that there are a lot of features in Visio that I'm not aware of, so that might be a good starting point. Is there anything in Visual Studio Team System that would be helpful? I've watched some demos on the product and I see that it has static code analysis, profiling, testing support etc, but it doesn't appear that it would be helpful for what I'm looking for. Automatic code generation doesn't work well for us either, since we are dealing with existing c++ applications and we generally don't create a lot of new classes. Drawing stuff out on paper (or a white board) is always a good idea. With this offshore design, we are finding that we need a high level of detail in the design. I think what would be helpful would be able to define classes and their member functions and include pseudo code with the member functions. I'm trying to get away from Microsoft Word. I find my self spending more time fighting Microsoft Word than I do thinking about design. I know Rational has some ability to generate some documentation. I think that alone would boost my productivity considerably.
Try StarUML which is an open source and really worth it.
-
Try StarUML which is an open source and really worth it.
Thanks. I took a look at StarUML. It feels like a good tool, but I seem to be finding UML to be quite unsatisfying. It seems too generalized. When I think of Object Oriented design, I still think in terms of programming. I think of words like inherits, derives, uses, interfaces, references, etc. UML allows you to model this infomation through generalizations, associations, compositions, etc, but these terms seem to generalized and difficult to understand. I would think that if I was creating a class diagram, I would want to use programming terms. What I think would be a great tool would be if you had essentially a class diagram. In each class, I could then define members and methods. You would then be able to described each member, describe the purpose of each method. Then it would be nice to be able to include psuedo code inside the class methods. This would all be done inside of some modeling environment. Then, when I'm done, I could generate a word document that would look similiar to what an API documentation would look like, complete with the descriptions and pseudo code. Then I can hand off the document to programmers that could implement it. I could do all this in MS Word, but it takes too much time formatting and fighting MS Word. I also have to do everything twice. Create the diagram in Visio, then write everything in WORD. Visio has an report tool, but it fills the document with UML lingo. It looks as if you can create Word templates for StarUML, but I couldn't figure out how to document the operations, nor do I have the first clue on how to create a suitable template. Does such a tool exist?
-
Thanks. I took a look at StarUML. It feels like a good tool, but I seem to be finding UML to be quite unsatisfying. It seems too generalized. When I think of Object Oriented design, I still think in terms of programming. I think of words like inherits, derives, uses, interfaces, references, etc. UML allows you to model this infomation through generalizations, associations, compositions, etc, but these terms seem to generalized and difficult to understand. I would think that if I was creating a class diagram, I would want to use programming terms. What I think would be a great tool would be if you had essentially a class diagram. In each class, I could then define members and methods. You would then be able to described each member, describe the purpose of each method. Then it would be nice to be able to include psuedo code inside the class methods. This would all be done inside of some modeling environment. Then, when I'm done, I could generate a word document that would look similiar to what an API documentation would look like, complete with the descriptions and pseudo code. Then I can hand off the document to programmers that could implement it. I could do all this in MS Word, but it takes too much time formatting and fighting MS Word. I also have to do everything twice. Create the diagram in Visio, then write everything in WORD. Visio has an report tool, but it fills the document with UML lingo. It looks as if you can create Word templates for StarUML, but I couldn't figure out how to document the operations, nor do I have the first clue on how to create a suitable template. Does such a tool exist?