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.