3 ms·

You, obviously, have no idea how hard it is to write decent documentation for any system. Especially when it has been in existence for many years. Good documen

You, obviously, have no idea how hard it is to write decent documentation for any system. Especially when it has been in existence for many years. Good documentation is hard and anyone who thinks it is not does not have a clue as to what is needed for the purposes of maintaining any piece of software. It is a very rare event to see documentation of a quality that explains all the interrelationships, reasons for the choice, etc, etc, etc. I have in the past been required to provide all the documentation for projects I have worked on, functional and technical specifications, user guides and cheat sheets, detailed design documents and all of these take considerable time to write well. I can't say I am expert in this area because I am not. But I have done a lot better than most of the projects that I have had to interface to over the decades. Documentation is a low priority for many management teams, they do not see the use in the kind of details that are needed. They do not give it sufficient support to do the job well. I have seen and worked with people who have the skill to write the kind of documentation that is actually needed and they are a rare breed, well worth any money you pay them. When companies complain about "cowboys", they often do not see that it is they who are the "cowboys".

repolfx 8y ago
You, obviously, have no idea how hard it is to write decent documentation for any system. Especially when it has been in existence for many years. I've been programming for decades and my current project is frequently praised by other developers who work with it (it's a framework) for the quality of its documentation. So, in fact, I do have such an idea. It's hard work. We do it anyway because we're professionals. The fact that people frequently don't do it doesn't change this. One technique I use is to keep documentation in the same repository as the code, and force people to write docs via the code review process. That is, a proposed change doesn't pass review until it also updates the documentation files. People want to get their code merged, so they know they'll have to take docs seriously or else it'll get picked up in review. Now maybe back in the mainframe days there was no culture of code review, but these are banks we're talking about. They excel at process. So it seems kind of unlikely they'd not want things documented, if management had understood what needed to be documented in the first place. But ultimately it was only the employees who knew that.
- oldandtired 8y ago
  Your current project is praised for its documentation, that's actually good. However, if you are taken out by a bus today in some permanent fashion, how easily or quickly can someone come up to speed in supporting your project and not have to try an puzzle out why you did things the way you did? What assumptions are there that you have not documented? What relationship to other pieces of code or system functionality is there that you have not covered? What changes cannot be done because of the "brittleness" of interrelationships between different sections of the code? What are the expected business rules that are applicable to the software? What constraints do they put on others who want to use the software? What are the meanings of all the magic numbers that are littered throughout your code? Keep in mind all those other questions that they will have along the way. It doesn't matter how "professional" you might be, you will not have covered all your bases. All you can do is spend lots of time in building up this documentation and if it is not being paid for in some way or time constraints get in the way, then none of it will get done properly. It is good to see that you have some sort of process in place to manage the problem, but code reviews are limited in what they will capture. I am documenting a piece of my own code at the moment for the purposes of submitting it to a specific project. It provides an additional functionality relating to something that the main system doesn't (at this point) handle. It is intended to be a simple workaround until the main system can supply this functionality at the VM and compiler level. I have just looked at one method that simply converts a hexadecimal number to a potentially multi-byte sequence. The detailed reasoning for the code (the assumptions, choices of numeric values used, etc) amount to 10 times the number of lines that is actual code and I still don't think it is complete. I think that it will take at least two, three or maybe even four more revisions in the documentation to get it to the place where someone else could make changes without causing problems elsewhere. The code itself is really simple. But, there is an additional purpose to this documentation, in that, it will provide a baseline against which the final system changes can be compared. I do this because, as a somewhat retired "professional" programmer, I want to see some serious documentation for this system and can afford to put in the time to do so. So back to the main discussions, unless full and complete documentation is a requirement put in place and strongly enforced, what documentation there is will not be sufficient for the future. It is a rare professional who will instigate this and make sure it happens. From my experience, such professionals that do this, have not come from a programming background but have come from other industries (usually engineering based) where such documentation is considered normal or is mandatory. I have seen few management teams that have given more than lip service to creation of the required documentation and the time frames they put on projects are such that there is little or no time for the production of quality documentation that is needed. Nor are they interested in paying for such. Banks have a focus of making money. They are not interested in spending it. The only process orientation they have is increasing the bottom line in whatever way they can. If it means they cut back on programmer and computing costs, they will do this. Ultimately, it is the bank management that holds responsibility to understand that the documentation is required. If they did not understand this, they should not have been in the position of management. It is irrelevant if only the employees (those grunts at the coal-face) knew this.

repolfx 8y ago

You, obviously, have no idea how hard it is to write decent documentation for any system. Especially when it has been in existence for many years. I've been programming for decades and my current project is frequently praised by other developers who work with it (it's a framework) for the quality of its documentation. So, in fact, I do have such an idea. It's hard work. We do it anyway because we're professionals. The fact that people frequently don't do it doesn't change this. One technique I use is to keep documentation in the same repository as the code, and force people to write docs via the code review process. That is, a proposed change doesn't pass review until it also updates the documentation files. People want to get their code merged, so they know they'll have to take docs seriously or else it'll get picked up in review. Now maybe back in the mainframe days there was no culture of code review, but these are banks we're talking about. They excel at process. So it seems kind of unlikely they'd not want things documented, if management had understood what needed to be documented in the first place. But ultimately it was only the employees who knew that.

oldandtired 8y ago
Your current project is praised for its documentation, that's actually good. However, if you are taken out by a bus today in some permanent fashion, how easily or quickly can someone come up to speed in supporting your project and not have to try an puzzle out why you did things the way you did? What assumptions are there that you have not documented? What relationship to other pieces of code or system functionality is there that you have not covered? What changes cannot be done because of the "brittleness" of interrelationships between different sections of the code? What are the expected business rules that are applicable to the software? What constraints do they put on others who want to use the software? What are the meanings of all the magic numbers that are littered throughout your code? Keep in mind all those other questions that they will have along the way. It doesn't matter how "professional" you might be, you will not have covered all your bases. All you can do is spend lots of time in building up this documentation and if it is not being paid for in some way or time constraints get in the way, then none of it will get done properly. It is good to see that you have some sort of process in place to manage the problem, but code reviews are limited in what they will capture. I am documenting a piece of my own code at the moment for the purposes of submitting it to a specific project. It provides an additional functionality relating to something that the main system doesn't (at this point) handle. It is intended to be a simple workaround until the main system can supply this functionality at the VM and compiler level. I have just looked at one method that simply converts a hexadecimal number to a potentially multi-byte sequence. The detailed reasoning for the code (the assumptions, choices of numeric values used, etc) amount to 10 times the number of lines that is actual code and I still don't think it is complete. I think that it will take at least two, three or maybe even four more revisions in the documentation to get it to the place where someone else could make changes without causing problems elsewhere. The code itself is really simple. But, there is an additional purpose to this documentation, in that, it will provide a baseline against which the final system changes can be compared. I do this because, as a somewhat retired "professional" programmer, I want to see some serious documentation for this system and can afford to put in the time to do so. So back to the main discussions, unless full and complete documentation is a requirement put in place and strongly enforced, what documentation there is will not be sufficient for the future. It is a rare professional who will instigate this and make sure it happens. From my experience, such professionals that do this, have not come from a programming background but have come from other industries (usually engineering based) where such documentation is considered normal or is mandatory. I have seen few management teams that have given more than lip service to creation of the required documentation and the time frames they put on projects are such that there is little or no time for the production of quality documentation that is needed. Nor are they interested in paying for such. Banks have a focus of making money. They are not interested in spending it. The only process orientation they have is increasing the bottom line in whatever way they can. If it means they cut back on programmer and computing costs, they will do this. Ultimately, it is the bank management that holds responsibility to understand that the documentation is required. If they did not understand this, they should not have been in the position of management. It is irrelevant if only the employees (those grunts at the coal-face) knew this.