The programming is insubstantial, Catsby.

May 14, 2006 7:54 AM

What kind of documentation will convince a non-software guy that writing a program is actual work?

I am in a semester long project group of four people, building a little electronic alarm. I'm the software engineer, the other three are all electrical students. One of them is pretty good (and knows some coding), but I feel that the other two group members aren't really very competent, either at the technical aspects or the teamwork. However, the issue is not in getting the project done, but in the peer evaluation rules for the end of semester. Three members of the team work together to assign a grade out of 15 to the other, and our individual assignment mark is modified by this evaluation.

My problem with this is that I have been pretty snarky about the way they're trying to run it and that I don't think they have any idea that I've done anything (software being fairly invisible). My attitude towards 'team meetings' and 'team work sessions' has degenerated (although this shows in my saying that we don't need to meet all day Saturday, rather than my not turning up when we do), because meetings turn into Competent Elec Guy explaining all the hardware to Incompetent Elec Guys, who treat meetings as a chance to do all the work they said they'd have done, and the incompetent guys are a liability when I'm debugging the hardware. I'm also terribly frustrated by their refusal (inability?) to use email as a means of actual communication, rather than a way to set up physical meetings and send me the agenda beforehand.

So, my question is: I'm trying to figure out ways of documenting all the software to show them I have been doing stuff; I have test programs ranging from 'check if we can output to pinB' to 'do everything!', and I've done up a graphical representation of the main program, but they still don't seem to think of it as anything but the single action item 'write and test a program'.

A super bonus would be strategies for making (/encouraging) people to see email as a legitimate way to 'talk' (probably a bit late for this one, with two weeks to go, but I'll know next time).

posted by jacalata to computers & internet (18 comments total)

You think most of them are incompetent, you're snarky to them, and you don't like to go the team meetings. I don't think any bit of documentation is going to solve this people problem.
posted by smackfu at 8:06 AM on May 14, 2006

You're right, there are people issues here. In my defence, their incompetence extends to not plugging the circuit into power, and then blaming my program for not receiving any signals. Some of the background is probably irrelevant, but I'm about to go to bed so I was including extra details to avoid need for clarification. (It may also have slipped into ranting: my apologies).

If it would be easier, think of the question as 'How do I create documentation that shows how much work I have done, clearly enough for someone completely unfamiliar with programming to appreciate it?' and ignore all the background.
posted by jacalata at 8:17 AM on May 14, 2006

What you learn in these group projects is how to deal with people in a team dynamic. These projects are going to be like countless more projects after you're out of school.

Some people will want to have a shitload of meetings when some of the issues can be done via email or the phone. You just have to adapt. If you think you can give status updates via email, then give an update via email in advance of the group meeting and ask the team to read it. Then you can spend your part of the status meeting explaining or answering questions. Lead by example.

Regarding the "proof you're not goofing off" part of the equation...

You can start by expanding the "Write and Test Program" part of the project timeline. You know it isn't a trivial one step process so document what goes into writing and testing the program and outline the time required in each step -- what can be done in parallel vs. serial. Substantiate the process. You'll need to do this for your boss in the future. You will also have to prove the sky is blue and that the sun rises in the east. Practice now and get good at it.

Most project plans I've had involving IT projects have a huge section in the "writing and testing" part. As the non-IT person I think of it as only writing and testing, but there is detail and reasons why it will take six weeks to write. If I saw a line item saying just "write and test program" and six weeks listed as the duration, I'd want to know why it couldn't be done in a day.

And check your attitude at the door.
posted by birdherder at 8:27 AM on May 14, 2006

It would be way easier to just ask the guys, "so, what mark are you thinking of giving me on the peer review?" If you're satisfied with their answer, great. If not, then ask how they'd rank their own contribution to the project. If there is a disparity, mention the number of hours you spent on the project and that you spec'ed, implemented, and debugged (whereas the h/w guys just implemented, if that).

Odds are, they'll give you a good grade without any prodding or documentation required. Give them a good grade too. Why are you turning a school project into something adversarial?

ps - You can't make people email, especially if one the people involved does not have a grasp of the material being discussed. It's actually less time consuming to impart new material face-to-face or over the phone, because you have additional non-verbal clues that indicate to you whether or not the person understands, and misconceptions can be cleared up immediately.
posted by crazycanuck at 8:31 AM on May 14, 2006

I suspect you'll be disappointed to find this is exactly how projects work after you get out of school. You're being graded on your ability to work in a realistic team environment. You should look at how to improve your own ability to work in an imperfect team, which will help both your grade and your future work. I sure wish I'd learned more of those lessons in school rather than figuring them out on the job.
posted by scottreynen at 8:37 AM on May 14, 2006

If you need something to document your code, Doxygen has passable Word and TeX output, and rather better HTML output. It'll also generate call graphs. You may need to reformat or improve your in-code commenting, however.
posted by Neon at 9:17 AM on May 14, 2006

I've run into similar situations at work, where I was the techie person, and others in the group were marketing, or users, or managers or whatever, and unfamiliar with the difficulties involved in coding.

One time, I simply printed out every line of code I had written for the project, and plopped that stack of dead trees on the conference table. It was an impressive display that got them to take me a little more seriously.

For next time, can you apply a little more formality to the project?

1) Document team meetings (especially any group decisions), and publish the minutes, so you all have a record of the project's progress, and what everyone has agreed to.

2) Write weekly status reports on what you've done personally, and what you still have to do, and insist your fellow team members do the same.

3) Keep track of specific beneficial things you've done for the project (especially if they are over and above what your role is in the project), so when performance review time comes, you have actual data about your performance, rather than relying on memory or your reputation.
posted by SuperSquirrel at 9:19 AM on May 14, 2006

scottreynen is exactly right. The actual project here does not matter much. In the "real world", you'll be thrown onto a team with two incompetents, a manager who doesn't care, and no prospect of escaping the situation when the semester ends. As an extra added bonus, the two incompetents are going to grade you, and if you think they're not going to give you a "1" out of 15 then I admire your optimism.

This is a people problem. Your problem has nothing to do with creating documentation. You could create a fully-debugged and tested 100,000 line program, with 6,000 pages of perfectly copy-written documentation, and you could still get a "1" out of 15 from those three guys. When you understand that, you will have moved to the next level.
posted by jellicle at 10:06 AM on May 14, 2006

I graduated with a degree in Computer Engineering from the UIUC, did a year of graduate school in Electrical Engineering, and have since been programming. So I've spent most of the last seven years working with both hardware and software! Good times.

Here's some advise, even though (as your suspect) it's probably too late.

1) You wanted to send email, they wanted to have meetings. An (informal) vote was taken: 1 to 3. Welcome to democracy, you just lost. What happens next is you go to all the meetings and try to make the most out of this lousy situation. Maybe you'll have better luck next time, but if you go off and do your own thing then the majority will do the same and forget about you.

2) Congratulations, you're smarter than some of the members of your group! For Heaven's sake, don't let them find out. They'll feel under attack then attack in return; it's called "being defensive". If someone is asking a poor question then you need to rephrase it for them (even if you know the answer, let the person they're asking say it). If you think someone is unclear on a concept then ask the question that they're too embarrassed to voice.

3) It's fairly easy to develop software individually. The inverse is true for hardware. Why? On my laptop I can build a complete development environment for almost any of my current projects. I have compilers, libraries, documentation, test harnesses, etc. But to do the same with hardware I'd need a logic analyzer, an oscilloscope, a protoboard with an FPGA, the flash harness, a robust power supply, and an assortment of common IC chips. In short: it's too expensive. EE are used to working together and sharing resources in a lab. Don't minimize their way of doing things.

4) Is your software feature complete? If not, then I wouldn't highlight all the work you've put into the test suites. Personally, I love unit testing, but your group members are going to look at it and say, "He spent a ton of time writing code that we won't even be graded on." You and I both know that isn't true, but that's what a novice sees. 80% of the projects I worked on in college only had to run under a very specific set of demo conditions. If that's their goal then it need to be your goal too. The best thing you could do is, when a hardware bug arises, show them how your test suite helps find their hardware bug. They need to see for themselves the value of your Above And Beyond The Call of Duty (that's how much you love the project) code provides.

Now, to perhaps answer your question: did you guys sit down and formally divide up all the responsibilities at the start? If so, then in the few remaining weeks you need to take some time at a meeting and go over the responsibilities list again. Sounding a humble as possible, point out that you've done all the work you were responsible for. And when it gets to the Incompetent Guys' share, lie and say you feel confident in whatever they were supposed to get done. Keep stressing their positive contributions -- even if you have to make some up -- and hopefully they'll remember that when evaluation time comes.
posted by sbutler at 10:13 AM on May 14, 2006

jacalata: that's an interesting situation you have, but nothing that can't be solved with some tact and reasoning.

1. focalize on common grounds: consider that if you must work togher with other people, and you MUST do that, everybody has an interest into making it as smooth as possible. Nobody has a right to screw up the process, not you nor the others, so first by understanding you are on the same boat you already are two steps ahead. Keep it present.

2. be "humble" and "interested" : find some topic of e-egineering that is related or exactly in the project and ask (don't DEMAND, ask) one of the engineers (not the coder one, unless the other two really are supertight assholes) if they could explain you something VERY EASY to explain , claim that you want to make sure "by asking a competent person" ..it's a compliment and it isn't phoney, definitely he's more likely to be competent on electronics then you.

3. find out of the work topics to talk : try spending some time togheter. Indeed E-engineers have more lab time togheter so learn to socialize with one another, sometimes because they don't want to fight over the oscylloscope :D ! Even if engineers, expecially construction/mecanic/electronic barely seem human to very social people, they are :D (I have a number of engineer friends and they still don't really like my teasing them with that..so I keep it to a minimum :) . Remember they are HUMANS, they have fears, they have problems, they like to laugh, they like to have good time, they have bad times.

Yeah that has nothing to do with the production of the good...BUT a good team can do fantastic things togheter when they go fine togheter, I promise you it's a lot better then having always _but only_ good individual accomplishment.
posted by elpapacito at 10:39 AM on May 14, 2006

There is helpful advice in the above answers, but they aren't emphasizing the key connection. It is a people problem and all involved are contributing. The solution is a well managed project. As in, good management is the solution to people problems.

To that end, SuperSquirrel's suggestions are great, but if you think of it as a 'see how much I did' exercise it won't really help - it is a management exercise, and the goal is the best project possible. Considering the late date, what you need to do is analyse the mark breakdown for the entire course (or lab portion of a larger course?) and do what you can to maximize your groups mark as a whole.

Finally, regarding the email thing.. I don't think you grasp the essential difference between electronics and software. Certainly you can email schematics back and fourth, but.. Among other problems, schematics are not a precise representation of the exact real world implementation. This is completely unlike source code, which is just next to a perfect representation of the implementation.
posted by Chuckles at 10:51 AM on May 14, 2006

There is helpful advice in the above answers, but they aren't emphasizing the key connection.

Well, I hadn't seen sbutler's and elpapcito's answers when I typed mine..
posted by Chuckles at 10:59 AM on May 14, 2006

Thanks for the feedback, all. I think I may have overstated matters a little: the project itself is on schedule and looks like it's going to get a good mark, and I haven't actually skipped any meetings, I'm just against these guys attitude of 'panic! Let's spend all our time in the lab together in case it doesn't get done on time!', which I feel is prompted by a lack of understanding about what is happening. I have also tried not to convey any negative attitudes about members to the team in question.

I'm heading to a meeting with the group now, so I'll bring up the evaluation and try to get a handle on how they see it, as crazy canuck suggested. I'll check back later.
posted by jacalata at 2:39 PM on May 14, 2006

jacalata: UQ 2nd/3rd year elec/comp-sys/software eng team project by any chance?

Although the "panic! Let's spend all our time in the lab together" thing may not necessarily seem constructive (and depending on the hours involved, stops being constructive some time after 2am), it might give the EE guys a chance to see what's actually involved in debugging if nothing else. Once they see what's involved they might realise that a "write code" bullet point is about as accurate as a "design, layout and assemble pcb" bullet point.

As a random tangent, assuming I've guessed right about your course, I find it kinda weird that the EE guys wouldn't know anything about software. E3210 (forgotten the title, but it was basically 68HC11 assembly) used to be compulsory for all EE/CSE students (although that predates the software engineering course).
posted by blender at 4:44 PM on May 14, 2006

with respect to documenting all your work: a friend of mine is a high-end software management consultant. He has decades of experience and a long string of spectacularly successful interventions to show for it. Because of that he can charge an exorbitant hourly rate for his services.

He has a technique to make the exhorbitant bill go down easier with his clients: along with the bill, he staples a log of what he was working on, for every hour charged. That log is precise to the 15 minutes. As a matter of habit, he pauses every 15 minutes and writes down what he his doing at that moment: "debugging getTime()", "still debugging", "refactoring a bit", etc.

It works for him, it might work for you.
posted by gmarceau at 8:49 PM on May 14, 2006

You picked it, blender. The two guys are friends who have transferred together from another uni, and seem to be seriously lacking fundamentals, especially in practical work. Them being friends is also a concern in terms of the evaluations.

The 'hours in the lab' are frustrating because the competent guy isn't always there, so I spend ages waiting for them to build a circuit that tends to not work in the end, which means that I can't really do any debugging for them to see anyway. Work that takes hours with them generally takes minutes with the third guy, but I don't know how to say I don't want to be there unless he's there. I would also be much happier to be doing it at 2am, when I'd normally be up anyway, but they schedule everything for 8am :)

I did bring up the evaluations today, but it got brushed off in a new panic over having broken a component (4th of 5 major components to break - lucky we were well under budget originally!), so I still don't know. I think I'll just focus on detailing exactly what I'm doing as we go through the testing, and hopefully when we get a working product we can at least agree to give each other all full marks -more than that might require excessive people management and confrontation.

(We do have documentation from assessed meetings during the course, but because minute-taking had to rotate, my ongoing explanations with diagrams of the test suite and functionality progress have been recorded as 'testing and programming: not complete' week after week).

gmarceau: that's something I'd been separately trying to start doing, to work on my own time management, but I hadn't really thought of applying it to this. Thanks!
posted by jacalata at 9:28 PM on May 14, 2006

jacalata: is Gordo still running it? FWIW, I did these back when they were E3291 and E3391. My first time round, our group imploded (as in not speaking to each other) and we scraped passes. The second time round we learned from experience.

Have you discussed any of these time management issues with your manager (assuming you still have an assigned fourth years)? I don't remember them participating in the marking (in fact I don't remember them doing anything other than silly Gantt charts), but they may be able to help defuse some of the tension.

Beyond that I can't really think of much more than has been offered upthread (good call by gmarceau). Perhaps offering a level of documentation of your software design that is on par with that of the hardware design. Block diagrams, flow charts, rationale for your design decisions, bugs you encountered and test cases you write prior to hardware availability, protocol specifications, design aspects of the hardware/software interactions and so forth. You'll need almost all of that for your project writeup (so it's not wasted effort), and being able to point to it and say "well, I did this" can't hurt your case.

Unless things have substantially changed, your entire group's mark will be largely constrained by whether it meets and/or exceeds specs on demo day. If it fails the demo, you can maybe salvage a pass on the strength of the writeup, but you really need to worry about making things work. Blaming people because the hardware is broken, or the PCB was messed up, or their soldering sucks, or the software is wrong doesn't help (that's not directed at you; just something most people involved in these subjects learn the hard way).

As you've probably discovered by now, the technical problems can seem relatively minor compared to the people problems. Chuckles pretty much nailed it. If everyone on the team works towards the success of the group, you'll do well. Easier said than done.

Off-topic: Damn kids. Get the hell off my lawn!
posted by blender at 11:10 PM on May 14, 2006

Yea, still Gordon Wyeth (I presume that's who you meant). I don't even know when they went to 8-digit course codes, so I'm guessing it was a little while ago :)

We don't have assigned managers now, there's just 2 tutors for the subject who will answer questions. But at the moment we meet about 50% of the specs, and I just have to test the interfacing of the last component to get the rest. I think it'll work out - the other guy in the group seems to share my perspective, and tends to do all the important stuff himself to save problems.
posted by jacalata at 9:46 PM on May 15, 2006