So, I bootstrapped/worked for some months on the core of a mid-sized project. The project integrates several technologies, enough for me to write some abstractions to ease the development.
The complexity of the system (and my tendency to over engineer, although I consciously try to avoid it) made enough abstractions, for it to be unclear the general flow of the program when looked without context.
We are a small company ( 7 programmers ), and the product has been out long enough for pesky intricate bugs to come to light. In the attempt of my coworkers to fix things, or to add functionality, they had a rough time since I scarcely documented it, they weren't that happy, although they admittedly were entertained. I even admit it takes me a little while to to fit my mind on the context after some months of not looking at the code (although I believe this is also because the domain is a little complex).
I'm happy with the structure of the project (but I admit in some parts it gets hard to follow, but that's just the nature of the problem), moreover the company can't afford restructuring the project. I'm writing some documentation on the modules/interfaces/etc. But there are some things hard to communicate. After mentoring with people it generally works out fine, I've also done this with other projects in the past, and person to person communication is very effective for them to understand the structure of what I had in mind ( ex. what I mean by SensorMonitor or what exactly is the DriverInterface functions responsability).
Also mainly because as programmers we tend to skim read looking for answers instead of engaging. So I'm not that sure my documentation is going to be effective.
I want the code to be useful, have a long life, and hopefully not annoying for the people that work in it. I'm trying to learn from good open source projects with good documentation to understand what they're doing right. I even believe that part of the success of a new tool/framework is how well documented it is (even more than usefulness)
So I turn to you, reddit programmers, what do other companies do to document the structure of their projects?
Is mentoring a good solution? If only documentation available, how to ease developers that want/need to contribute?
Also, we don't have a lot of time to spend documenting, so any help on tools and standards used would be great.
Thanks!
submitted by /u/mynjj
[link] [comments]
from Software Development – methodologies, techniques, and tools. Covering Agile, RUP, Waterfall + more! https://ift.tt/2J78JhG