[Linias]

Hi all,

Question about best practice / what other teams are doing. We are in an internal debate in my group about who authors and writes help files / ballon tags / etc.

Requirements / Test is under the same manager and claim that the Design or Development group should be adding help balloons into the code and create the chm files that explain what each field does. They claim that they need this in order to determine if the software functions correctly. It's a somewhat reasonable argument.

Design and development groups both claim that coders should not be writing help files. Their expertise is in coding, not english (and indeed many of them have terrible grammer, are aweful at explaining from a user perspective how to do stuff, but are very good coders). Also a reasonable arguement.

How are other groups doing this? When are your chm files generated? Who creates the text, what tools do they use to do it, and if it's not development, how do they know what the feature is to describe and how it works?

thank you in advance!

[modi123_1]

I guess it is all up to the companies. I have always written my own help files, FAQs, and testing documentation. Some places have teams of tech writers that do it as well, but if the base isn't there from the programmer's point of view the tech writers need to fall back on the design documents generated before the coding. Of course those might not be there or were never updated so features and functionality go unnoticed or not commented on.

It's an imperfect system but it works.

I get really annoyed by the perpetuated myth that "developers cannot talk to anyone". It went from super annoying to tedious quickly.

This post has been edited by modi123_1: 08 July 2011 - 12:04 PM

[tlhIn`toq]

chm files? Is it 1980 again? Cool, I love the music.

Quote

Their expertise is in coding, not english (and indeed many of them have terrible grammer, are aweful at explaining from a user perspective how to do stuff, but are very good coders). Also a reasonable arguement.

A good reason to not outsource your code to foreign countries. Not to mention the whole "Hire American, the job you save might be your own." concept. Stop perpetuating the cliche that programmers are nerds in their mother's basement with no social or English skills. Either that or quit hiring India to write your software. Or stop hiring the cheapest college student. You get what you pay for and that includes employees.

One of the underlying principals at our company about our software is that if it requires a manual then it wasn't written very well.

Quote

that explain what each field does.

If you have to explain what each field does then it is REALLY poorly written.

Big slow company with too many employees said:

Gosh, this field is next to a label marked "First name". I guess we need to send this off to the documenation team to write a half paragraph on what it's for.

Tooltips and ballon help are written by the coder as they write the application, in our company. It just makes sense as they already have the component/form open. We wouldn't trust a non-coder to scrub through all the custom controls and forms to add tooltips and balloons: They'll break something.

[Linias]

Completely understand it's up to the companies. :-) Obviously for a one-man shop, it doesn't work - there is only one person and you have to do it all. :-)

The problem I have is that all the groups (requirements, design, development, test) are all pointing saying "we shouldn't be doing it. That group should".

I want to fight that with good, hard solid procedures that other companies use that work.

A lot of the bottom line features are often not determined until development. Design does not bring it all the way to filling out every field. They say that it too tedious and at that point they might as well complete the development and what would the developers do then? So that really pushes it to the developers, or having the testers (who do a lot of the user documentation as well) go back in and fill in the help information.

so, how are other companies (with seperated groups) doing this? Do their designers go down to field level and put in every balloon that says what you should put there, filling in the chm files and includeing screen shots? Do the developers do it? Does test go back afet the software is tested and fill that in? Is it a seperate group? Who do they report to in the manufacturing chain?

[tlhIn`toq]

Quote

The problem I have is that all the groups (requirements, design, development, test) are all pointing saying "we shouldn't be doing it. That group should".

Sounds like you have too many employees and they are too secure in their jobs. Find the guy that is eager to actually work for a living, who volunteers to do this stuff and keep him and fire the rest.

Quote

Is it a seperate group? Who do they report to in the manufacturing chain?

I'm curious what company you work for developing software that has SO MANY teams and people. It sure seems like you are saying there are so many people that your company is tripping over each other finding ways to NOT do anything.

Are you interested in a coder that actually WORKS and doesn't bitch about doing their job? As well as writing the documentation on the fly so when a program is done it is DONE. I'd love to work someplace where I got some help.

[Linias]

tlhIn`toq, on 08 July 2011 - 12:13 PM, said:

Quote

Their expertise is in coding, not english (and indeed many of them have terrible grammer, are aweful at explaining from a user perspective how to do stuff, but are very good coders). Also a reasonable arguement.

A good reason to not outsource your code to foreign countries. Not to mention the whole "Hire American, the job you save might be your own." concept. Stop perpetuating the cliche that programmers are nerds in their mother's basement with no social or English skills. Either that or quit hiring India to write your software. Or stop hiring the cheapest college student. You get what you pay for and that includes employees.

I'm sorry... I find that highly offensive. In fact I will have you know they come from a variety of races, but are all American. We do not outsource this coding, thank you. Nor are they college students or recent grads. They have degrees, and I will wager some of them can proably program circles around you. I love the job they do, and they are very highly skilled professionals.

That said, most of them (with one exception as his degree is in English lit) are not very good at documentation. They do not like it. They do not spell because they prefer spell checks. And honestly they have a hard time doing documetation becuase they have trouble seeing the application from a user perspective. they tend to think everyone knows what they know and people are going to be naturally highly intelligent, skilled people who are using the apps.

however, our apps are international and many people using them are not computer geniuses. they are minimum wage workers.

I am not saying our programmers can not communciate clearly. I am saying they make poor help documentation writers.

Quote

One of the underlying principals at our company about our software is that if it requires a manual then it wasn't written very well.

Yes, and I am sure the ISO9000 board will have no problem when we tell them we don't document because the application is so simple a squirrel can use it.
And I am sure our customers who all require documentation will give us the bid and cross out the section about requireing training and documentation because we claim our software is so simple to use.
your company must not make software that gets sold, much.

Quote

Quote

that explain what each field does.

If you have to explain what each field does then it is REALLY poorly written.

Big slow company with too many employees said:

Gosh, this field is next to a label marked "First name". I guess we need to send this off to the documenation team to write a half paragraph on what it's for.

Again, requirements my friend. Our procedures and our customers require it - we have to add it.

[Linias]

tlhIn`toq, on 08 July 2011 - 12:25 PM, said:

Quote

The problem I have is that all the groups (requirements, design, development, test) are all pointing saying "we shouldn't be doing it. That group should".

Sounds like you have too many employees and they are too secure in their jobs. Find the guy that is eager to actually work for a living, who volunteers to do this stuff and keep him and fire the rest.

Quote

Is it a seperate group? Who do they report to in the manufacturing chain?

I'm curious what company you work for developing software that has SO MANY teams and people. It sure seems like you are saying there are so many people that your company is tripping over each other finding ways to NOT do anything.

Are you interested in a coder that actually WORKS and doesn't bitch about doing their job? As well as writing the documentation on the fly so when a program is done it is DONE. I'd love to work someplace where I got some help.

Don't confuse out employees with the managers of the groups. Most of my employees are more then willing to do the work. The managers however try to avoid out of scope costs for them as they get blames for the cost over-runs.

Our ISO procedures and our processes require that we have seperate teams - requirements, design, development, test and deployment. they also take different skill sets. Our requirements people are trained to go to a site and liason with the customer to determine their needs. they are not coders. design and development often cross paths as they have similar skill sets. Test however is a different animal. It's required to be seperate from development (this ensures that development can not influence test to pass software that has bugs). QA watches over the entire process to make sure it's all followed so our software is as bug free as possible.

[modi123_1]

Quote

That said, most of them (with one exception as his degree is in English lit) are not very good at documentation. They do not like it. They do not spell because they prefer spell checks. And honestly they have a hard time doing documetation becuase they have trouble seeing the application from a user perspective. they tend to think everyone knows what they know and people are going to be naturally highly intelligent, skilled people who are using the apps.

Jesus.. how much would your company be willing to pay someone who can code, write, see things from the user's side, *and* is willing to volunteer for projects? A quad threat!

Quote

A lot of the bottom line features are often not determined until development. Design does not bring it all the way to filling out every field. They say that it too tedious and at that point they might as well complete the development and what would the developers do then?

The programm would know the language and system. The specs should be able to be plunked down in any language and completed. The programmers then make the vague wordy statements and actions into methods and classes. I've worked in a job where they were pushing this - it failed. Hard. They persisted so eventually I just wore the hats of everyone in the chain and got back to work.

Quote

The problem I have is that all the groups (requirements, design, development, test) are all pointing saying "we shouldn't be doing it. That group should".

I want to fight that with good, hard solid procedures that other companies use that work.

I guess where do you fit into this whole process? What is your roll in the machine?

Quote

so, how are other companies (with seperated groups) doing this? Do their designers go down to field level and put in every balloon that says what you should put there, filling in the chm files and includeing screen shots? Do the developers do it? Does test go back afet the software is tested and fill that in? Is it a seperate group? Who do they report to in the manufacturing chain?

I've been in companies where the testers write up the documentation. That's their other hat besides testing. They have the UX side down.

I've worked where I am the writer for both. I naturally see it both ways and can explain the tasks out.

Designers rarely would do it, but project managers might.

[Linias]

modi123_1, on 08 July 2011 - 12:39 PM, said:

Quote

That said, most of them (with one exception as his degree is in English lit) are not very good at documentation. They do not like it. They do not spell because they prefer spell checks. And honestly they have a hard time doing documetation becuase they have trouble seeing the application from a user perspective. they tend to think everyone knows what they know and people are going to be naturally highly intelligent, skilled people who are using the apps.

Jesus.. how much would your company be willing to pay someone who can code, write, see things from the user's side, *and* is willing to volunteer for projects? A quad threat!

I have 3 people in the group who can do this (I am one of them, + 2 others). And yes - we value those who can do that. In general though most of my developers prefer to develop. They do not want to write documentation. they do not want to run project schedules. they do not want to deal with customers. They want to be allowed to sit in their corner with their computer and bang code. It's what they live for. And I acknowledge and appreciate that. They are darn good coders, and I would take a darn good coder any day over a mediocre coder who also did documentation.

We allow anyone in the group to fullfill any need they have the skill set for. So, if I have a coder who can do Bids and Propsals, and they want to, I am more then happy to have them do it. If I need a tester and a developer feels like it, he's welcome to lend a hand in test - except he can not test his own code (against procedures) and he reports to test during that period.

People who are good at doing all of the above though are more rare finds for us. I just hired a new one - I am hoping he can turn into someone who can do it all, because right now the 3 I have who can are over-worked.

Some of the others will try, but they are not very good at it.

Quote

Quote

The problem I have is that all the groups (requirements, design, development, test) are all pointing saying "we shouldn't be doing it. That group should".

I want to fight that with good, hard solid procedures that other companies use that work.

I guess where do you fit into this whole process? What is your roll in the machine?

I am the design manager. On top of that, I am trying to modify our processes to make things work better.

This whole complication came up when a tester came to me because he was having trouble determining what a feature was supposed to do. He asked the developers start including help documentation. The development manager responded back in the thread that he does not want developers writing documentation because they are bad at it, and he argues they should not be the ones doing it.

So, I have test on one hand saying development should do it and development saying test should do it. It's not techincally my problem, but I look at it as my job to make things work here, so I am trying to work out a compromise. I am the perfect person to do it because both the other managers listen to me. But I need to come up with a clean, cohesive arguement about why it should be one or the other. there will be push-back, but the engineering manager will also back me if I have a good argument about how and why other shops do it this way.

Quote

Quote

so, how are other companies (with seperated groups) doing this? Do their designers go down to field level and put in every balloon that says what you should put there, filling in the chm files and includeing screen shots? Do the developers do it? Does test go back afet the software is tested and fill that in? Is it a seperate group? Who do they report to in the manufacturing chain?

I've been in companies where the testers write up the documentation. That's their other hat besides testing. They have the UX side down.

I've worked where I am the writer for both. I naturally see it both ways and can explain the tasks out.

Designers rarely would do it, but project managers might.

It gets done... because it has to. But it never gets done without someone complaining that it was not their job.

I want to MAKE it someones job so that we can avoid arguments in the future. right?

This post has been edited by Linias: 08 July 2011 - 12:59 PM

[Linias]

If it helps, here are some parts of the thread so you can see the arguments:

Tester:

Quote

Having just gone through much of our documentation I would like to recommend that a more creative and user friendly method be looked into to provide user and admin support for our products. The way we have been trying to keep the docs in step with the products needs to be improved. The current method of placing screen captures into Word docs, and then trying to keep screen captures and written content current with GUI changes needs to be done away with.

I would hope that there is some way for the developer to describe each data entry field and each label that will appear on the GUI in the code and when the user is using the app they could right click on the field or label to access that description.

I would also recommend an intelligent search tool (like Google) be included to answer user’s questions in dealing with out apps. This search tool would query each of the developer entered description field and well as any “How To” procedures that would be included separately in conjunction with a tester/doc person. This How To content would then be the only thing that needed updating when changes were made.

Development Manager:

Quote

My two cents. Ideally, it would not have to be the developer that includes tag text. A lot of that should come from requirements and design so the documentation could conceivably be generated by the requirements and design docs as well as from code (ex. CHM files and similar). In other discussions, we’ve talked about screen mockups, mock apps, and HF activities upstream from development so we don’t have people like me, <developer>, and <developer> doing GUI design decisions.

Now I am already pushing Designers on the GUI design decisions. But I am trying to resolve the rest of it.

[modi123_1]

Jesus man - they are not asking for documentation they are asking for an overhaul on how you write code! I can see deploying internal group "wikis" out there, but "right click on the field or label to access that description. " screams of rewriting entire class libraries. Not to mention could you imagine how annoying that would be to use? It makes me gag on things like Excel let alone someone I wrote. That and how slow it would be to fill out some comment template for all items. "Length: 20 characters, validate: type, content, tab-able" and so on?

Back in the day when I was a tester my job was to make up test cases the included type and length. Any document ambiguity was cleared up when we had the meeting to sign off on the testing document between the programmers, testers, and designers.

Honestly it sounds like a communication problem that should be resolved before the testers start.

[tlhIn`toq]

Quote

Yes, and I am sure the ISO9000 board will have no problem when we tell them we don't document because the application is so simple a squirrel can use it.
And I am sure our customers who all require documentation will give us the bid and cross out the section about requireing training and documentation because we claim our software is so simple to use.
your company must not make software that gets sold, much.

Now who is going out of their way to be deliberately offensive and antagonistic?
Yeah. We're piddly. A couple million dollars a year for a company with less than a dozen employees. Our product line is just used in amusement parks around the world by a few thousand people to gross millions of dollars in revenue for our clients. I filled my passport in the first two years with all the business trips, and had to have pages added.

Quote

however, our apps are international and many people using them are not computer geniuses. they are minimum wage workers.

Yep, just like ours. Sounds just like the trained chimps they hire at the amusement parks to run the software we write. Singapore, Australia, Dubai, USA... It doesn't seem to be any different. They are all base-pay clerks. And these are not people who read the manuals, so the software has to be intuitive. Personally I find it a great coding challenge to write software that needs a minimum of training and documentation. If it is intuitive to need little training, and robust enough to not allow users to do harmful things, and fast enough to process thousands of park photo sales while keeping queue lines short, then I have done my job well.

That's why I asked who you were doing all this for. There is a huge difference in how things get done and who is responsible, between a company of a dozen people and a company of a dozen office buildings.

Quote

And honestly they have a hard time doing documetation becuase they have trouble seeing the application from a user perspective.

That sounds like a communication problem from the top, downward. How can can anyone be expected to write good, intuitive software that gives a good customer user experience if they don't know what the user experience is or is supposed to be. Just a thought here, but maybe taking an extra week to put the developers on the ground at the client site so they can see and experience what the users are doing, the work flow and the needs would GIVE them the user's perspective and improve the quality of you final product. Along the lines, it would reduce the cycle of build, critique, change spec, re-write, QC, deploy, {repeat}

Quote

They do not want to write documentation. they do not want to run project schedules. they do not want to deal with customers.

I don't necessarily *want* to do those things either. But I like having a paycheck. I don't always want to be away from home two months at a time doing an installation. Or on a plane 13 hours per leg for 27 hour travel days. But that's a part of the job. I can't think of too many jobs where you only have to do the parts you *want*. I think all jobs have portions that are not a job. But it's part of the job description and we do it if we want to keep the job and keep food on the table.


Dude, lead by example.

Quote

They do not want to write documentation. they do not want to run project schedules. they do not want to deal with customers.

however, our apps are international and many people using them are not computer geniuses. they are minimum wage workers.

other. there will
Don't confuse out employees with the managers of the groups.
your company must not make software that gets sold, much.
perspective. they tend to think everyone
so, how are other
needs. they are not coders. design and development
[...]

It puts you in a tenuous position when your communications are fraught with the types of issues you say make the coders poor documentarians.

Quote

I'm sorry... I find that highly offensive. In fact I will have you know they come from a variety of races, but are all American. We do not outsource this coding, thank you. Nor are they college students or recent grads. They have degrees,

Hey, don't get offended. I have NO IDEA what company (gov't agency perhaps) you are with. Could be two people, could be 20,000. Just that it is a company that had to come to a forum to get help figuring out it's work flow. From what you are saying those degrees don't guarantee real-world skills that are needed for a well-rounded employee. But that's a topic that has been discussed to death. Give me a 45 year old that has done the job for 15 years even with no paper to back it up, over a college degree with no experience and a chip on his shoulder about making his mark on the world. I'm a bleed red-white-and-blue patriot, but I know that being American doesn't mean you can read and write above an 8th grade level. Ever been to Detroit? Text messaging has done more to harm writing skills than anything else I can point at. Kids pass everything because teachers can't hold them back even if they are brain dead. Diplomas and degrees only tell me the person is experienced at institutional living. So is a convict.

Might I suggest you re-visit the hiring process and testing? Perhaps you could find a few coders that can code and write documentation well if the testing were adjusted for it. I'm sure you could find 50 right here on DIC.

[Linias]

tlhIn`toq, on 08 July 2011 - 01:50 PM, said:

Hey, don't get offended. I have NO IDEA what company (gov't agency perhaps) you are with. Could be two people, could be 20,000. Just that it is a company that had to come to a forum to get help figuring out it's work flow. From what you are saying those degrees don't guarantee real-world skills that are needed for a well-rounded employee. But that's a topic that has been discussed to death. Give me a 45 year old that has done the job for 15 years even with no paper to back it up, over a college degree with no experience and a chip on his shoulder about making his mark on the world. I'm a bleed red-white-and-blue patriot, but I know that being American doesn't mean you can read and write above an 8th grade level. Ever been to Detroit? Text messaging has done more to harm writing skills than anything else I can point at. Kids pass everything because teachers can't hold them back even if they are brain dead. Diplomas and degrees only tell me the person is experienced at institutional living. So is a convict.

Might I suggest you re-visit the hiring process and testing? Perhaps you could find a few coders that can code and write documentation well if the testing were adjusted for it. I'm sure you could find 50 right here on DIC.

Well, now we are talking more civilly. :-) And I agree with you 100%. My philisophy on hiring is simple: I prefer people who want to work, and learn and try hard to people who have experience, but no drive. I also prefer people who have figureed things out the hard way, then just had it handed to them on a degree that means nothing. Back when I got my MCSE (and this was before M$ added adaptive testing), I remember going into the test, and the person next to me literally had someone read them the questions. Apparently the testing center allowed that. I have no idea if they passed, but at that time I lost all respect for certifications.

Now, getting onto what people want to do and what they can do.... I also have to play with the hand I have been dealt. I am sitting on a number of people who have years of experience in the field and with our programs. I can't just come in and fire everyone and start fresh - the amount of knowledge we would lose would be incalculable and would cripple us. Also, politally these people have friends in the organization (and it's a big organization of which we are only a very small part). My best hope is to replace through attrition. It's the political reality I have on my hands. I can do that - I just hired one guy who I hope will work out well. But it takes time.

At the same time, we have learned from experience that if we put one of these guys as a project lead, projects overun costs and timelines, and it costs our company millions. Likewise, if I ask them to do documentation, when it gets to QA, it all gets rejected and we have to do it all over again - this time with the person who I should have had do it in the first place.

Talking about realities, we come to our customers. I am sure everyone on here can tell you about how crazy customers are, and you have your own tales as well, I am sure. The fact of it is, and I can rant and rail against it all I want, the customer require a certain level of documentation. To give you an example of what I mean - our average BID REQUIRES 300+ pages of documentation to support it. That's the BID, mind you. For training, they REQUIRE NO LESS then 2 2-week trips of training. Regardless of if we tell them we can train them to use it in 1 day, it's that simple. It doesn't matter. That is their requirement. They do not negotiate on the matter. Our choice is we bid that, and potentially win it. Or we don't and one of our competition who does bid it wins it. If we want the business, we have to comply. Many require that we put developers on-site for the first 3 months of operation (some even want 24 hour support), so I assure you each and every one of them has spent time on the ground. It's not unusual for us to have 4-5 people on a given site for the first few months. One of our customers (oddly enough, Dubai as you mentioned) required that we sit there even if there was nothing wrong. They just wanted someone there on site at all times, 24/7. So, we had to rotate people in and out to keep it staffed at all times.

However, as much as these guys spend on site, they think it's sufficient to say in the documentation "Fill in the required fields and hit next" as the required fields are all obvious things (like Date / Time and Names or Values), and each field and each one had a * next to it in red with a note at the bottom that said "* is a required field". However, a customer made us revise the documentation (and our idiotic salesteam agreed to do it at our cost) because it did not state IN THE DOCUMENTATION that the * denoted a required field, and did not list what each required field was, how many characters it accepted, and what characters were not allowed. Doesn't matter that the software wouldn't let you put a '/' in there, or that it gave you a friendly error saying that character was not allowed. The fact is the documentation didn't state that '/' was not allowed, so it SHOULD BE. And since the documentation did not state that there was a maximum of 30 characters for the first name, the software should allow for unlimited (or the documentation must be modified).

My boss expressed it best when he described our install team. He said if they have instructions on how to use the bathroom, they would wet their pants if there wasn't a step to undo their zipper.

In the meantime, I am looking to solve my one problem - do I just push back to test that they should be doing all the documentation, and have a discussion with a developer when they are confused, or do I push back on development to fill this in, and have test vet and fix anything that sounds off? And for that matter, what mechanism can I use to easily expose these things so test can modify them if they need to without mucking around in code, but at the same time without making config files or localtext files that are bigger than the number of stars in the sky?

[modi123_1]

Quote

do I just push back to test that they should be doing all the documentation,

This one, because...

Quote

and have a discussion with a developer when they are confused, or do I push back on development to fill this in, and have test vet and fix anything that sounds off?

... it sounds like the testers vet it either way so make them do the majority of the work and ask questions as needed.

Quote

And for that matter, what mechanism can I use to easily expose these things so test can modify them if they need to without mucking around in code,

I am a bit lost now - which "these things"? How a particular field works or the type of input? Either through inter-team meetings or have the developers keep a file - a *TECH* file - that lists the screens and controls on them and what the controls do. The testers take that and add words to make the clients happy. win-win and everyone shares the writing burden at some level.

[jon.kiparsky]

Quote

Tooltips and ballon help are written by the coder as they write the application, in our company. It just makes sense as they already have the component/form open. We wouldn't trust a non-coder to scrub through all the custom controls and forms to add tooltips and balloons: They'll break something.

That's why that stuff isn't in the code. Literal text lives alongside the code, where it can be edited by someone who didn't write the program, but speaks whatever language you're localising to. English, maybe, or Italian, or whatever - the program should work the same.

It's great that you've got programmers who take that on, but why not arrange things so their writing can be edited without having to tug on their sleeve and ask them to make a bunch of changes?