Documents
-
It is really important to document everything, imagine the problem that could happen if you or one of your co-workers leaves the company... Apart from that, there are some standards and rules that force you to document if you want to follow them. I've been in both sides... asking to document and hating to document... moreover typically you will get everything perfectly documented except the thing you will need most and you won't remember... This was a poor attempt to make you feel better... probably too poor... :~
[www.tamelectromecanica.com] Robots, CNC and PLC machines for grinding and polishing.
Sorry, my fault for not explaining it clearly: we had sufficient documentation to complete the project: these new management brats are asking for extra documentation so they can show their bosses that they are doing something to justify their pathetic existence. It's just dumb.
"If you think it's expensive to hire a professional to do the job, wait until you hire an amateur." Red Adair. nils illegitimus carborundum me, me, me
-
Why are non-techies put in charge of techies? They clearly can't cope and have little or no idea what to do so resort to those old management nuggets: write a document, do some overtime, get more bodies. We were getting along quite nicely, no real problems, on time and on scope. Then, for reasons divulged only to those far above my pay grade a host of managers were introduced and we have slowed right down because very teeny-weeny thing we do has to be documented. So we're falling behind. The answer? Overtime. Okay, that's fine for the most part but it isn't the answer: you can only work so long before productivity nose dives and you van end up even farther behind. Not overtime? How about some more resources? Doh! (Slaps head) Why didn't I think of that? Get some more grunts in, waste even more time training them and then hope we can make up the lost time. Why can't these 'managers' develop a spine and tell the business what the real situation is? Maybe that way they'd actually head up a project that doesn't get canned for being months over due. </EndRant>
"If you think it's expensive to hire a professional to do the job, wait until you hire an amateur." Red Adair. nils illegitimus carborundum me, me, me
-
Why are non-techies put in charge of techies? They clearly can't cope and have little or no idea what to do so resort to those old management nuggets: write a document, do some overtime, get more bodies. We were getting along quite nicely, no real problems, on time and on scope. Then, for reasons divulged only to those far above my pay grade a host of managers were introduced and we have slowed right down because very teeny-weeny thing we do has to be documented. So we're falling behind. The answer? Overtime. Okay, that's fine for the most part but it isn't the answer: you can only work so long before productivity nose dives and you van end up even farther behind. Not overtime? How about some more resources? Doh! (Slaps head) Why didn't I think of that? Get some more grunts in, waste even more time training them and then hope we can make up the lost time. Why can't these 'managers' develop a spine and tell the business what the real situation is? Maybe that way they'd actually head up a project that doesn't get canned for being months over due. </EndRant>
"If you think it's expensive to hire a professional to do the job, wait until you hire an amateur." Red Adair. nils illegitimus carborundum me, me, me
digital man wrote:
We were getting along quite nicely, no real problems, on time and on scope. Then, for reasons divulged only to those far above my pay grade a host of managers were introduced and we have slowed right down because very teeny-weeny thing we do has to be documented.
If your employer holds an ISO certification... there may be strict documentation requirements. If the documentation has been deemed inadequate then there is a possibility of your employer losing the ISO certificate. Without the ISO certificate some customers could be forced to discontinue using the company software because of government/inter-corporate regulations. Quit complaining and get back to work. :) Best Wishes, -David Delaune
-
Sorry, my fault for not explaining it clearly: we had sufficient documentation to complete the project: these new management brats are asking for extra documentation so they can show their bosses that they are doing something to justify their pathetic existence. It's just dumb.
"If you think it's expensive to hire a professional to do the job, wait until you hire an amateur." Red Adair. nils illegitimus carborundum me, me, me
:rose: it is the only thing that can have sense then...
[www.tamelectromecanica.com] Robots, CNC and PLC machines for grinding and polishing.
-
digital man wrote:
We were getting along quite nicely, no real problems, on time and on scope. Then, for reasons divulged only to those far above my pay grade a host of managers were introduced and we have slowed right down because very teeny-weeny thing we do has to be documented.
If your employer holds an ISO certification... there may be strict documentation requirements. If the documentation has been deemed inadequate then there is a possibility of your employer losing the ISO certificate. Without the ISO certificate some customers could be forced to discontinue using the company software because of government/inter-corporate regulations. Quit complaining and get back to work. :) Best Wishes, -David Delaune
Randor wrote:
If your employer holds an ISO certification
Nope: this is really a tussle between agile and waterfall. We are an agile shop: all of the new managers come from a waterfall background and are struggling to understand how and what we do hence are trying to squeeze square-waterfall into a round-agile hole. Ain't going to work.
Randor wrote:
Quit complaining and get back to work.
You're right: as long as they pay me I'll do whatever and take my frustrations out on you lot! :-)
"If you think it's expensive to hire a professional to do the job, wait until you hire an amateur." Red Adair. nils illegitimus carborundum me, me, me
-
digital man wrote:
We were getting along quite nicely, no real problems, on time and on scope. Then, for reasons divulged only to those far above my pay grade a host of managers were introduced and we have slowed right down because very teeny-weeny thing we do has to be documented.
If your employer holds an ISO certification... there may be strict documentation requirements. If the documentation has been deemed inadequate then there is a possibility of your employer losing the ISO certificate. Without the ISO certificate some customers could be forced to discontinue using the company software because of government/inter-corporate regulations. Quit complaining and get back to work. :) Best Wishes, -David Delaune
-
Sorry, my fault for not explaining it clearly: we had sufficient documentation to complete the project: these new management brats are asking for extra documentation so they can show their bosses that they are doing something to justify their pathetic existence. It's just dumb.
"If you think it's expensive to hire a professional to do the job, wait until you hire an amateur." Red Adair. nils illegitimus carborundum me, me, me
Whenever there is a change in executive management, they have to do something, they have to. They would have to provide some graphs, numbers etc. There was a change in the executive team of one of our customer. The first thing he did.. lets go for some other software, that's it. I find it dumb too, but otherwise after an year the management guy will not have anything to show.
-
Randor wrote:
If your employer holds an ISO certification
Nope: this is really a tussle between agile and waterfall. We are an agile shop: all of the new managers come from a waterfall background and are struggling to understand how and what we do hence are trying to squeeze square-waterfall into a round-agile hole. Ain't going to work.
Randor wrote:
Quit complaining and get back to work.
You're right: as long as they pay me I'll do whatever and take my frustrations out on you lot! :-)
"If you think it's expensive to hire a professional to do the job, wait until you hire an amateur." Red Adair. nils illegitimus carborundum me, me, me
It sounds like there is a big communication gap between the "coders" and the "managers." I think that maybe you guys should not take the blame, but you can take some responsibility to fix the situation. It is the responsibility of the employees to inform their managers about how things really get done. If agile works and it's an improvement over waterfall, try to educate them. Try to find out what the "real" goal of the managers is. Maybe documentation isn't really the goal, but the means to the goal. Maybe after finding out what they "really" want, you can get them there better. We are a small ISO-13485 company (kind of like ISO-9000 but for medical devices). That and our FDA requirements means a lot of documentation. But, the Engineers have learned what the FDA and ISO really requires and we constantly tweak our processes to become more efficient. In some ways, it's uncomfortable that we're never quite in the "flow" and no two projects run the same, but at least we are continuing to do the "overhead" work more efficiently. So, point it, talk to your managers and see if maybe there isn't some win-win way to work. Good luck.
-
Why are non-techies put in charge of techies? They clearly can't cope and have little or no idea what to do so resort to those old management nuggets: write a document, do some overtime, get more bodies. We were getting along quite nicely, no real problems, on time and on scope. Then, for reasons divulged only to those far above my pay grade a host of managers were introduced and we have slowed right down because very teeny-weeny thing we do has to be documented. So we're falling behind. The answer? Overtime. Okay, that's fine for the most part but it isn't the answer: you can only work so long before productivity nose dives and you van end up even farther behind. Not overtime? How about some more resources? Doh! (Slaps head) Why didn't I think of that? Get some more grunts in, waste even more time training them and then hope we can make up the lost time. Why can't these 'managers' develop a spine and tell the business what the real situation is? Maybe that way they'd actually head up a project that doesn't get canned for being months over due. </EndRant>
"If you think it's expensive to hire a professional to do the job, wait until you hire an amateur." Red Adair. nils illegitimus carborundum me, me, me
This is all gospel truth. Brooks's Law guarantees that adding manpower to a late project will make it later. Worse, external artifacts -- non-compilable description and documentation of a program -- can easily drift from the program itself, creating more confusion than would arise from not having the artifacts in the first place. Such drift appears to be guaranteed by something akin to Parkinson's Laws. We'll never have a perfect solution. The best we can do is to make our stuff capable of guiding the user to the maximum possible extent: validating his input; making sure he knows what's about to happen; getting confirmation of permission to proceed at every relevant step; and so forth. The GUI revolution was supposed to bring us closer to that goal...but the greatly increased complexity of our programs since GUIs became commonplace has cross-cut it badly. As for managerial interference, there's never been a solution to that, either.
-
Why are non-techies put in charge of techies? They clearly can't cope and have little or no idea what to do so resort to those old management nuggets: write a document, do some overtime, get more bodies. We were getting along quite nicely, no real problems, on time and on scope. Then, for reasons divulged only to those far above my pay grade a host of managers were introduced and we have slowed right down because very teeny-weeny thing we do has to be documented. So we're falling behind. The answer? Overtime. Okay, that's fine for the most part but it isn't the answer: you can only work so long before productivity nose dives and you van end up even farther behind. Not overtime? How about some more resources? Doh! (Slaps head) Why didn't I think of that? Get some more grunts in, waste even more time training them and then hope we can make up the lost time. Why can't these 'managers' develop a spine and tell the business what the real situation is? Maybe that way they'd actually head up a project that doesn't get canned for being months over due. </EndRant>
"If you think it's expensive to hire a professional to do the job, wait until you hire an amateur." Red Adair. nils illegitimus carborundum me, me, me
Two things 1. Managers have requirements that have to be met, maybe they are not passing on sufficient information to you. That's their fault! 2. Stop moaning , you are getting paid for the work that they deem necessary. A lot of people out there would like a job. - That's your fault! Conclusion you guys are all at fault talk! Well there we go - that one semester Human Resources and Management course really paid off for me! :)
-
Why are non-techies put in charge of techies? They clearly can't cope and have little or no idea what to do so resort to those old management nuggets: write a document, do some overtime, get more bodies. We were getting along quite nicely, no real problems, on time and on scope. Then, for reasons divulged only to those far above my pay grade a host of managers were introduced and we have slowed right down because very teeny-weeny thing we do has to be documented. So we're falling behind. The answer? Overtime. Okay, that's fine for the most part but it isn't the answer: you can only work so long before productivity nose dives and you van end up even farther behind. Not overtime? How about some more resources? Doh! (Slaps head) Why didn't I think of that? Get some more grunts in, waste even more time training them and then hope we can make up the lost time. Why can't these 'managers' develop a spine and tell the business what the real situation is? Maybe that way they'd actually head up a project that doesn't get canned for being months over due. </EndRant>
"If you think it's expensive to hire a professional to do the job, wait until you hire an amateur." Red Adair. nils illegitimus carborundum me, me, me
-
Why are non-techies put in charge of techies? They clearly can't cope and have little or no idea what to do so resort to those old management nuggets: write a document, do some overtime, get more bodies. We were getting along quite nicely, no real problems, on time and on scope. Then, for reasons divulged only to those far above my pay grade a host of managers were introduced and we have slowed right down because very teeny-weeny thing we do has to be documented. So we're falling behind. The answer? Overtime. Okay, that's fine for the most part but it isn't the answer: you can only work so long before productivity nose dives and you van end up even farther behind. Not overtime? How about some more resources? Doh! (Slaps head) Why didn't I think of that? Get some more grunts in, waste even more time training them and then hope we can make up the lost time. Why can't these 'managers' develop a spine and tell the business what the real situation is? Maybe that way they'd actually head up a project that doesn't get canned for being months over due. </EndRant>
"If you think it's expensive to hire a professional to do the job, wait until you hire an amateur." Red Adair. nils illegitimus carborundum me, me, me
On the flip side I am certain we all remember what working with no documentation is like, hell I can remember doing work on a very complicated php website with screwy implementations of everything from the facebook/twitter apis to basic stuff like database connectivity. After that, and learning I would not wish that on anyone ever again I always document well. As to managers, meh they are idiots if they were intelligent they would not need us now would they, so buck up and get at it, I bet you will rock whatever you are working on.
-
Why are non-techies put in charge of techies? They clearly can't cope and have little or no idea what to do so resort to those old management nuggets: write a document, do some overtime, get more bodies. We were getting along quite nicely, no real problems, on time and on scope. Then, for reasons divulged only to those far above my pay grade a host of managers were introduced and we have slowed right down because very teeny-weeny thing we do has to be documented. So we're falling behind. The answer? Overtime. Okay, that's fine for the most part but it isn't the answer: you can only work so long before productivity nose dives and you van end up even farther behind. Not overtime? How about some more resources? Doh! (Slaps head) Why didn't I think of that? Get some more grunts in, waste even more time training them and then hope we can make up the lost time. Why can't these 'managers' develop a spine and tell the business what the real situation is? Maybe that way they'd actually head up a project that doesn't get canned for being months over due. </EndRant>
"If you think it's expensive to hire a professional to do the job, wait until you hire an amateur." Red Adair. nils illegitimus carborundum me, me, me
digital man wrote:
and we have slowed right down because very teeny-weeny thing we do has to be documented.
That represents a failure in correctly implementing the methodology. Unfortunately a common problem. But it is not a condemnation of the methodology itself.
digital man wrote:
Why can't these 'managers' develop a spine and tell the business what the real situation is?
Of course the real solution is that the managers boss should be telling the managers that their job depends on correctly implementing the methodology. (Similar to the difference between delivering code and delivering code that runs and even code that runs well.)
-
I'm trying to scope out how to do documentation here. It is varying between cigarette-packet and war-and-peace depending who writes it - coders go for brevity and Sales like detail. On the one hand, we should document what is being done, but does 5 pages make sense for a two line change? If it's in the centre of a core component then yes, but when it's the UI to move a field I call JFDI. Unfortunately, I need to have a coherent plan that everyone can follow.
Panic, Chaos, Destruction. My work here is done. Drink. Get drunk. Fall over - P O'H OK, I will win to day or my name isn't Ethel Crudacre! - DD Ethel Crudacre I cannot live by bread alone. Bacon and ketchup are needed as well. - Trollslayer Have a bit more patience with newbies. Of course some of them act dumb - they're often *students*, for heaven's sake - Terry Pratchett
Nagy Vilmos wrote:
On the one hand, we should document what is being done, but does 5 pages make sense for a two line change? If it's in the centre of a core component then yes, but when it's the UI to move a field I call JFDI. Unfortunately, I need to have a coherent plan that everyone can follow.
Of course. But the idealized point of process control is that one documents what one is already doing. Thus if you have actual requirements for that two line change, then you write them down. If you don't have those requirements then you don't. And although the first case might seem extreme but when billable hours are involved for larger contract firms documenting every single change order (and billing for it) can be the difference between profit and loss.
-
Randor wrote:
If your employer holds an ISO certification
Nope: this is really a tussle between agile and waterfall. We are an agile shop: all of the new managers come from a waterfall background and are struggling to understand how and what we do hence are trying to squeeze square-waterfall into a round-agile hole. Ain't going to work.
Randor wrote:
Quit complaining and get back to work.
You're right: as long as they pay me I'll do whatever and take my frustrations out on you lot! :-)
"If you think it's expensive to hire a professional to do the job, wait until you hire an amateur." Red Adair. nils illegitimus carborundum me, me, me
digital man wrote:
Nope: this is really a tussle between agile and waterfall. We are an agile shop: all of the new managers come from a waterfall background and are struggling to understand how and what we do hence are trying to squeeze square-waterfall into a round-agile hole. Ain't going to work.
I doubt that agile precludes documenting processes. If that is the case then I can only wonder exactly what is in all of the books that cover agile. Obviously trying to mesh methodologies without planning is a problem. A management problem. That however is not a methodology failure.
-
This is all gospel truth. Brooks's Law guarantees that adding manpower to a late project will make it later. Worse, external artifacts -- non-compilable description and documentation of a program -- can easily drift from the program itself, creating more confusion than would arise from not having the artifacts in the first place. Such drift appears to be guaranteed by something akin to Parkinson's Laws. We'll never have a perfect solution. The best we can do is to make our stuff capable of guiding the user to the maximum possible extent: validating his input; making sure he knows what's about to happen; getting confirmation of permission to proceed at every relevant step; and so forth. The GUI revolution was supposed to bring us closer to that goal...but the greatly increased complexity of our programs since GUIs became commonplace has cross-cut it badly. As for managerial interference, there's never been a solution to that, either.
Fran Porretto wrote:
can easily drift from the program itself, creating more confusion than would arise from not having the artifacts in
Just as failure to review code can lead to code that is hard to maintain, buggy and fails to meet requirments. But that too is a failure in process implementation and not a failure of the methodology itself.
Fran Porretto wrote:
We'll never have a perfect solution.
There are however companies that are successful and are using process methodologies extensively and strictly. And they attribute their success to that implementation. Might note as well that at that level they can measure their success too. So it is certainly possible to get something that is a lot better than the standard developement practices.
-
digital man wrote:
Nope: this is really a tussle between agile and waterfall. We are an agile shop: all of the new managers come from a waterfall background and are struggling to understand how and what we do hence are trying to squeeze square-waterfall into a round-agile hole. Ain't going to work.
I doubt that agile precludes documenting processes. If that is the case then I can only wonder exactly what is in all of the books that cover agile. Obviously trying to mesh methodologies without planning is a problem. A management problem. That however is not a methodology failure.
I have run into this bottleneck mentality as well, thinking that Agile--iterations, user stories, and tasks are only meant to create a working software product. If the documentation is also a 'deliverable', then it must be factored into the project scheduling, including each iteration. Each document will need a user story, tasks for creating it, and tasks for reviewing. If it makes the project longer, then so be it. If the new documentation is a new request (demand), then handle it as such and add the appropriate user stories for each document requested. This will expand the schedule, but, that is to be expected. If there is a newly added process for documenting, then add it to the schedule. That will be a required part of the project. As far as the overtime goes, it only works for a short while, then productivity drops off.
-
This is all gospel truth. Brooks's Law guarantees that adding manpower to a late project will make it later. Worse, external artifacts -- non-compilable description and documentation of a program -- can easily drift from the program itself, creating more confusion than would arise from not having the artifacts in the first place. Such drift appears to be guaranteed by something akin to Parkinson's Laws. We'll never have a perfect solution. The best we can do is to make our stuff capable of guiding the user to the maximum possible extent: validating his input; making sure he knows what's about to happen; getting confirmation of permission to proceed at every relevant step; and so forth. The GUI revolution was supposed to bring us closer to that goal...but the greatly increased complexity of our programs since GUIs became commonplace has cross-cut it badly. As for managerial interference, there's never been a solution to that, either.
Hire more people to write the documentation! Hmmm, then they'd be pestering the programmers for explanations and the programmers wouldn't be able to tell them to just RTFM. Hire more programmers to explain the code to the documentors! I suspect an infinite loop of diminishing returns. :wtf: ---- Seriously, one place I worked, we had programmers and documentors running in parallel. We'd get together, discuss where the code is going, piss off the documentors when they realize they'd have to rewrite pages because of the changes we made. But for the most part it all worked. It posed no real impediment to our programming. In some instances, the documentors (as in user documentation) would complain what we had developed was impossible to explain and we would work to create a different, better user interface/experience. I miss those days. Then I worked at another company that had a three inch thick binder of instructions to follow to document any project. I followed it once and when I was done I realized it documented everything but the program. It also required managers sign off on all the major progress points. Since witch hunting was the favorite sport there, nobody, but nobody, was going to put pen to paper and leave a trail to them if the project went into the crapper. Of course the real fun was when the company was buying this 12 binder set of project methodology that was going to simulateously give us perfect programs, wonderful documentation, and keep us on schedule and under budget. The joke was that this company had not yet finished the two most important binders of the series. Sorta cast a cloud over the whole "on time and under budget" thing. Upper management was gungho on us using it regardless. And then I discovered a financial link between the methodology company and the upper management and then it all made sense. Fortunately it died a deserved death.
Psychosis at 10 Film at 11