Fog Creek Software
Discussion Board

Writing skills


I work on a project of about 25+ people. In my opinion the architect on our project has terrible writing/communication skills. Here is an example from one of the documents he worked on:

One other addition in our new class is the addition of the isOwner Boolean value.  The details on the use of this are explained in more detail later.

I think this becomes more clear as:

Our new class also has an isOwner Boolean value. Details on using this are explained later.

It seems like everything he writes takes about twice as many words as necessary (as well as almost always using passive voice). I realize I am not the best writer either, but I think carefully written documentation really helps out on large projects. What do other people think?

Also, I am just a "lowly" developer on this project (5 years exp). Any ideas on tactfull approaches to get this guy to use better wording?


Friday, May 24, 2002

It appears he's trying to sound "technical" or "official." Too many technical explanations sound stinted like that. I suspect just talking to him about it might fix the problem. Explain the wordiness is cumbersome.

Troy King
Friday, May 24, 2002

Wow!  I wish I had you're problems!  We don't even have documents were I work.  You get handed an idea for a project and you are expected to start coding.  Our veep doesn't see anything wrong with it, he's always done it that way!  Oh well, as long as there paying me!

The Raging /.'er
Friday, May 24, 2002

I find the term "architect" to be overused these days. 

From what I can tell, this term almost seems to have originated with the book "The Mythical Man Month", where Brooks notes that had he allowed the architects to do their job the OS/360 would have been a far more robust product.

This is a fine context for architect.  In fact, I would specifically state that an architecture group, or individual, is necessary when:
1. The technology is so large or complex or interdependent that there needs to be a specific focal point for design.
2. The technology is so new that mere mortals don't maintain the math skills necessary to keep up with the inventors.

Are there any reasons I missing?  With respect to item #1, I often find that many systems don't have an excuse to be so large/complex/interdependent.  That they can be simplified into simpler individually managed segments.

With respect to item #2, there truly is a need for enlightened, above the fray, experts.  In this case you often truly do need an architect/senior scientist type person to organize design.

Howver, in most cases, it is more useful to have technical experts in individual areas: a codec expert, a security expert, a networking expert, ...  These people with specific expertise which the rest of the team can draw upon for sanity checks and design reviews.  True experts in their fields who have deployed their work several times in the past and have already learned from some mistakes.

I find the term architect more ridiculous when the architect is defining class members.

Nat Ersoz
Friday, May 24, 2002

>> I find the term architect more ridiculous when the architect is defining class members. <<

Nat, thanks for your thoughts. I agree with your post for the most part. But the proper roles for an architect wasn't really part of my question.

From my example you assumed our architect mainly defines class member - that's not really true (but I can see how you would think that). I just happened to choose one of the 2-3 paragraphs defining a member out of a 15 page document.

In defense of our project I would say we need an architect because of your problem #1. We have over 20,000 classes in the source repository. My "project" is really a subproject working to extend the existing code for a certain market. Other teams are either supporting the frameworks or working on other market areas.

In agreement with you - I think the architect for my project is a control freak who doesn't trust the developers (or other teams). As Troy pointed out earlier he tries "to sound technical or official". I have been in numerous meetings where this architect has insulted or demeaned other peoples work.

Anyway, I don't want to open a whole can of worms on this. I am just trying to work within my "sphere of influence" and improve the little areas. I've only been at this company since last fall and I'm trying to give it a chance.

Maybe in a couple weeks there will be another post from me asking how to improve the rest of my job :)

Friday, May 24, 2002

Although I do agree the term architect is probably overused in software, I think architects are not only necessary on large complex systems or systems where you need truly enlightened individuals.

A traditional building architect can be someone who designs a simple house (or more likely simply signs off on the design) or they could be the one designing the world's largest sky scraper. One would obviously be more qualified than the other but both use the job title "architect". So we could apply the same logic to software. Someone who designs the software could be called the architect, regardless of complexity. But I agree that the weight of the title implies level of intelligence, experience, and skill.

Ian Stallings
Friday, May 24, 2002

I agree with NathanJ that clear writing is important for communication on a project. However, the ability to write clearly is a skill that takes time and effort to acquire. If you want someone to improve his writing, you'll need to convince him that there is a problem, and that it is worth his time to correct it.

It is possible that he is capable of writing more clearly than he does, but that he can't afford the time needed to edit what he has written. Editing is a time-consuming task, so he might be stopping once the text says what he means, even if it could be clearer. In this case, you'd need to convince him that it is worth his time to edit his writing more. Alternatively, you could volunteer to edit his writing for him. He might be open to this, especially if it frees up more of his time to do other work.

Whether or not this is worth addressing depends on the context. If he is touchy about it, and if his writing is good enough that you can figure out what he means, it might be best to just live with it.

Greg Shoom
Friday, May 24, 2002

Wow, 20K classes, that is pretty awesome.  I can imagine that it takes a group of people to organize that sort of size.  I can surely understand maintaining a central focus for this sort of project.

Nat Ersoz
Friday, May 24, 2002

NathanJ, my short advice to you is not to worry about it. You are fortunate to be a better writer and communicator than the architect. You won't get him or her to change, and he or she won't be able to quickly either. Writing skill requires talent and training. Pointing out the flaws will just get him or her offside.

In a few years you will probably be doing better than the architect. The ability to clearly perceive and communicate issues is extremely powerful.

Amuse yourself by analysing his or her mistakes, but keep it to yourself.

Hugh Wells
Friday, May 24, 2002

Also, try to find the things the architect does well and focus on those. No sense resenting someone over something like this.

Hugh Wells
Friday, May 24, 2002

I'd like to second Hugh Wells' comments.  As long as your architect's writing communicates the essential ideas (albeit in a wordy fashion) it is better to focus on how you can improve rather than on how he can improve.

If you were this person's mentor or manager, then it would make sense to approach him.  But as a junior member of the staff, my best advice to you is to look, listen and learn so that someday, when you are the architect, you will be criticized for something else entirely!  ;-)

Mark Brittingham
Saturday, May 25, 2002

Details later will be coming, classes also shall become clear.

Simon Lucy
Monday, May 27, 2002

Funny Simon!  Imagine Luke filling a complaint with HR about Yoda's communication skills.  Don't laugh, but I'm reading How to win friends & influence people.  First rule:  Don't criticize.  It never does any good.  Just makes the situation worse.  Sorry, I haven't gotten to the influencing people part yet!

The Raging /.'er
Tuesday, May 28, 2002

>>  First rule: Don't criticize. It never does any good. <<

Thanks to everyone for the advice to just deal with it. I see where you all are coming from.

But how do you know when to offer advice and when not too? I disagree with the "never does any good" idea. If someone on your project kept using abbrvtdvrblnms wouldn't you find that distracting and confusing? Trying to introduce nonAbbreviatedVariableNames would help the project.

Then again maybe I am just resentful. I worked on many smaller projects before my current job. I usually had a free hand in how I worked. My projects were (almost) always successful. Now I am on a large project. In many respects I have a lot less responsibility for the success of this project. It's frustrating to watch other people create all this unnecessary complexity.

As for my original problem, I've noticed a lot of people on my project getting confused. A number of the developers are non-native English speakers. I feel it is NOT helpful to have hundreds of pages of hard to read requirements.

I think I'll just offer a few small improvements and he can ignore/use my advice as needed. I won't worry too much if it doesn't go anywhere.

Tuesday, May 28, 2002

Maybe you could volunteer to be the documentation wrangler.  Rough copies come to you and you polish them up.  You could pass it off as trying to help the architect by freeing up some of his time so he doesn't have to concentrate on useless details.

The Raging /.'er
Tuesday, May 28, 2002

Not that anybody asked me but I often find myselft presented with solutions that basically amount to "do it yourself".

Your "document wrangler" suggestion would probably help the project but would you really get rewarded for it?  I suspect not.  I suspect that the original author will get credit for his good work while the original poster gets a heavier workload.

My Project Manager barely speaks english.  When he does speak he doesn't have any information.  Our clients are frustrated.  I brought up my concerns to my manager (who I often turn to for advice) and she said I should meet with the business clients to help him.

I've also been told that since he's weak with schedules I should do that for him too.  At some point I'm doing two jobs.  (And no, I don't have an interest in being a project manager)  Anyway, I wish there was a better answer than "do his job for him".  However, I don't have it.

Anonymous Coward
Wednesday, May 29, 2002

Anonymous Coward... The best answer is to eliminate the incompetent and to get on with the primary job of performing work for the client.  It sounds like in your position, that isn't considered the primary job, and is probably way down on the ole priority list, with "being nice" at the top of the list where "nice" has it's original definition (i.e. stupid, gullible).

There is no better answer when the objectives are in direct conflict.  For example... you do your project managers work, he gets the "credit", you get more workload.  You don't do the extra work, you are labeled as not a "team player".

Of course you are being used.  If you won't stand up for what is right, then your only choice is to keep your head in the sand and continue to go along to get along.

By not doing anything yourself, you condone the activities you find objectionable.  Whining about the situation while not taking action only demonstrates a lack of personal integrity.

Don't take this personal... there are a lot of people in your situation.  The situation is self-inflicted... and I will guess it has a lot to do with the golden handcuffs of a paycheck.

Joe AA.
Thursday, May 30, 2002

>> There is no better answer when the objectives are in direct conflict. For example... you do your project managers work, he gets the "credit", you get more workload. You don't do the extra work, you are labeled as not a "team player". <<

Sometimes this is the case. Sometimes not. Usually when I "help" someone with their problems I then become the expert. Have you ever been in a meeting where the person responsible for a task has to turn to you for the answers to questions about their area?

If I edit/proofread the design documents for my project I'm sure I would gain a better understanding of the system than most of the other people here. Also, I'm probably more likely to articulate the architecture than the architect. Not a bad situation even if I don't get "credit".

Anyway, I agree that it isn't helpful to just sit around whining unless you are willing to put in some time to fix the problem yourself. Sometimes you can offer advice and people take it. Othertimes you have to help them out. I also agree that helping other people can suck a lot!

Thursday, May 30, 2002

"Our new class also has an isOwner Boolean value. Details on using this are explained later."

Can be written even more clearly:

New values in OwnerClass:
Name: isOwner
Type:  boolean
Details: {actual details here}

For this kind of thing, a reference-like format is best. The only possible audience for this information is developers--as opposed to BizDev, Marketing, Usability, or any other spec audiences.  Clarity and brevity is more valuable than any other characteristic for this audience.

Friday, May 31, 2002

Isn't this the purpose of UML - the describe classes, their attributes and interactions?

Nat Ersoz
Friday, May 31, 2002

The main problem of UML is that whatever it's INTENDED to do, it's ACTUAL role is to describe, in excruciating detail, the classes, structures and interactions of the project just BEFORE the most recent major crisis.
Because that was when everyone stopped the horrible overload of maintaining the UML and switched into "code and fix"...

Katie Lucas
Tuesday, June 04, 2002

Maybe you could leave a copy of this on his desk:

Thursday, June 06, 2002

*  Recent Topics

*  Fog Creek Home