• Post Reply Bookmark Topic Watch Topic
  • New Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Devaka Cooray
  • Knute Snortum
  • Paul Clapham
  • Tim Cooke
Sheriffs:
  • Liutauras Vilda
  • Jeanne Boyarsky
  • Bear Bibeault
Saloon Keepers:
  • Tim Moores
  • Stephan van Hulst
  • Ron McLeod
  • Piet Souris
  • Frits Walraven
Bartenders:
  • Ganesh Patekar
  • Tim Holloway
  • salvin francis

Software Architecture toolbox  RSS feed

 
Greenhorn
Posts: 1
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi, im a soft eng and would like some practical advice.

My current role requires me that I document new software in a way that a developer should be able to fully implement it with minimal to no doubts when implementing it.

what would be the minimun, yet sufficient artifacts to provide him in this case.

I need something that defines the classes in detail and how they communicate between each other.

I thought a class diagram and a sequence diagram get closer to this with some additinal written notes.

Also if anybody is willing to be my mentor, I would really appreciate it. I need somebody to put me on track in the shortest period of time possible.
 
Sheriff
Posts: 13473
222
Android Debian Eclipse IDE IntelliJ IDE Java Linux Mac Spring Ubuntu
  • Likes 1
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator

Kalos Solak wrote:My current role requires me that I document new software in a way that a developer should be able to fully implement it with minimal to no doubts when implementing it.


This is an unrealistic expectation to have when you are dealing with any non-trivial problem. If you have never solved this before and the programmer has never solved this before, how do you expect to know what kind of problems you'll run into as you're developing the software? Even when you are familiar with the problem domain, there are so many different things that can vary. Do not deceive yourself into thinking that you can be successful with this "throw over the wall to the developer" mentality. Many hundreds of thousands to millions of man-hours have shown that it's a virtual certainty that there will be doubts and new questions once you start writing the code.

Instead, you should plan on doing incremental development. Discover and refine as you go. Experiment and test early and often.

what would be the minimun, yet sufficient artifacts to provide him in this case.



(Note: this paragraph is meant to be read with a healthy dose of sarcasm and with tongue firmly planted in cheek) If are really bent on pursuing your pipe dream of being a clairvoyant and omniscient architect, then you need the results of your palm reading, tea leaf reading, star chart, astrological tables, Ouija board session results, and three jackpot-winning lottery tickets. With that irrefutable proof of your ability to foresee the future, you can confidently hand the thick MS-Word document that you labored for weeks or months to write, knowing fully well that your prophetic abilities have allowed you to cover everything that nobody else in the world could possibly know beforehand.

Otherwise, start with a very general plan, maybe a high-level context diagram and plan on working very closely with your developers as you and they work as a team to flesh out and GROW a viable architecture and design. See the previous comment about incremental development, experimenting, and testing early and often. Expect your understanding of the system and your requirements to change over time. It's not unrealistic to expect that to happen often and rapidly. Be prepared to deal with change.


I need something that defines the classes in detail and how they communicate between each other.

I thought a class diagram and a sequence diagram get closer to this with some additinal written notes.


Yeah, that might be a start but those kind of diagrams are best drawn on a whiteboard as you discuss, test, refactor, and refine your application as you discover what you really need the system to do. Get plenty of whiteboard cleaner and maybe a good camera so you can capture ideas and drawings as you go.

Also if anybody is willing to be my mentor, I would really appreciate it. I need somebody to put me on track in the shortest period of time possible.


Here's some free advice: there are no shortcuts when it comes to developing software. Software development is hard work. It takes time, patience, and above all, skill. These are all things are not very compatible with "the shortest period of time possible" unless you measure time in terms of months and years.

So, you either spend the time to learn and refine your understanding as you go, keeping your system in a constant state of "wellness" or you can take a wild stab at what you think the system should do and rush things out the door and then spend the next X years (or however long it takes for you to give up and move on to the next mess you're going to make) trying to fix all the problems that you created for yourself and your team in trying to rush things out in the first place.

Sorry if this sounds mean or cynical. I'm not trying to be mean but I am very cynical when someone thinks that they can go into this kind of thing with that "throw over the wall" mentality and come out with a well-written, well-architected solution. At best, it's a sign of naiveté and inexperience; at worst, it's a sign of hubris and ignorance, a lethal and often costly combination.

Software development involves a lot of learning, not only about the problem domain and the application requirements but also about the process of writing software itself. Too many software developers and aspiring architects try to rush headlong into things they know very little to nothing about. Without a plan for learning and applying that learning back into the work that you're doing, you're just putting yourself on the fast track to failure that many have traveled before you.

Here are some wise words from a recognized expert in our field, Robert "Uncle Bob" Martin: "The only way to go fast, is to go well."

---
If you are looking for a book with good suggestions about the kind of documentation that makes sense for a team that commits to learning and incrementally growing the architecture and design of a software system, I suggest you pick up a copy of Simon Brown's Software Architecture for Software Developers. This is a book I have used myself to guide my work.
 
Junilu Lacar
Sheriff
Posts: 13473
222
Android Debian Eclipse IDE IntelliJ IDE Java Linux Mac Spring Ubuntu
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I thought I was done but I have a little more ...

I need something that defines the classes in detail and how they communicate between each other.


Did you mean the code? Because that's really the only thing that can define the classes and the functionality in detail. Anything else is merely an approximation.

Don't think for a second that a diagram can define a class "in detail" -- it can't and it never will. You may say that "A picture is worth a thousand words" but when it comes to software development, which a very precise craft, the fewer words the better because that means your code and design is simpler and easier to maintain. And how is the developer supposed to figure out what the right "words" are that he should choose to fill in the gaps that a diagram does not and cannot explicitly spell out? Where is the programmer going to get the ideas that will help him find the right words to use to turn your awesome, detailed picture into full-fledged, working program code?

Here's the simple answer to that: The programmer is going to need to get those words from YOU, the architect who has the vision of the solution, and the CUSTOMER who has the detailed knowledge of the needs that your software system must satisfy. That can only be done through many CONVERSATIONS and ITERATIONS of trying out versions of the software that are written. As you come up with each new version, you have to go through the same process of TESTING and letting the user ACCEPT what you've done so far. You need to get their FEEDBACK as to what you've missed or misunderstood. Most of all, you have to go through this whole process of discovery, experimentation, learning, and feedback AS MANY TIMES that it will take until the customer says it's good enough for his purposes. For now. Then you need to get ready to do it all over again when it no longer is enough for what the user needs to do.
 
Ranch Hand
Posts: 91
3
Chrome Java Windows
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
This reminded me of:

Vroomfondel wrote:“We demand rigidly defined areas of doubt and uncertainty!”




I've had all those issues Junilu described just with myself as the architect and programmer.  You start with a plan and inevitably have new questions and discover new capabilities as you implement and refine (or even scrap and replace) the plan.

And, yes, taking pictures of whiteboards is a thing, as is, "DO NOT ERASE!"


Fundamentally, you may be trying to fit a traditional project management peg into an agile project's hole.
...or using "static" everywhere in your OOP...
 
Julian West
Ranch Hand
Posts: 91
3
Chrome Java Windows
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
The second video in this free course addresses your situation:

https://www.udemy.com/java-design-patterns-tutorial/learn/v4/content

(I just watched it and remembered this thread)
 
Bartender
Posts: 20765
124
Android Eclipse IDE Java Linux Redhat Tomcat Server
  • Likes 1
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
The six deadliest words in Information Technology:


All You Have To Do Is...



Computers are stupid. They have no common sense. They do what you tell them to do and not what you want them to do. That's why a realistic estimate for a project should be at least twice what you "know" it's going to take, no matter how simple the project. You wouldn't believe all the things that can go wrong when you do a devil's-deal with a computer. I've seen stuff that had to be corrected in "Hello, World!" programs. Indeed, IBM has a program called IEFBR14 whose sole purpose in life is to do absolutely bnothing and it still went through multiple bug-fix releases. One or 2 of which, I believe were post-year 2000, despite the fact that the program itself was written somewhere around 1960-x.

And that's not counting what happens when you give specs to code monkeys. If you're dealing with cultures who are conditioned to accept what the boss says unconditionally, you end up having to program the programmers as much as you do having to program the computers.

I do believe in design documents. Generally an executive summary (1 or 2 pages) to say what and who the system's for. A functional spec that details what the system must do and how it must do it. Often a user's guide so that not only can the system users have formal instructions, but so you can cross-check the functional specs against intended operation. Frequently an administrator's guide like the user's guide but with sensitive information in it.

I do these as living documents, meaning that I don't write everything to perfection before progressing (in a panic because I spent 6 weeks of an 8-week project doing documentation), but rather hit the high points, and go back and note changes and discoveries. Ideally, these documents would be authoritative for the entire project lifespan, although of course in the real world, who's got time to do all that and besides after the project went into production the entire development team was liquidated. Ideally, in an Agile shop, there would be someone designated to do the document updates at each milestone to record what the previous milestone did and what would be addressed in the next milestone.

Fred Brooks defined a development group as a team in his seminal book The Mythical Man-Month and one of the distinctive positions within his conceptual team was a full-time librarian. However in the Real World, we consider ourselves lucky if the lead programmer isn't also the sysadmin, network admin and DBA. And sometimes the electrician and HVAC engineer.
 
Junilu Lacar
Sheriff
Posts: 13473
222
Android Debian Eclipse IDE IntelliJ IDE Java Linux Mac Spring Ubuntu
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator

Tim Holloway wrote:The six deadliest words in Information Technology:


All You Have To Do Is...


I thought it was


You Can Probably Do This In...


Seriously though, I absolutely agree with all that you said.
 
That's a very big dog. I think I want to go home now and hug this tiny ad:
how do I do my own kindle-like thing - without amazon
https://coderanch.com/t/711421/engineering/kindle-amazon
  • Post Reply Bookmark Topic Watch Topic
  • New Topic
Boost this thread!