Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

This is just a question to think about.

When you write technical documentation and programming comments, do you ever find yourself writing run-on sentences in order to be more precise?

Is packing more technical information into one sentence better than creating many little sentences each with a little bit of technical information?

I know it's better to have lots of little classes in their own little files. Perhaps this doesn't apply to writing?

share|improve this question
1  
I would not necessarily vote to close, however a migration to english.stackexchange.com might be appropriate. On principle, however, technical documentation relating to software probably does belong here. –  temptar Jun 23 '11 at 12:14
    
Run-on sentences are illegal in English and maybe a few other languages. Were you assuming English? In some other languages run-on nature is considered poetically beautiful and a basic IQ test. Those languages are much better suited for prose and poetry than English, but are not good for describing technical/computer systems. –  Job Jun 23 '11 at 15:15
    
@temptar: Technical writing as it specifically relates to software is probably on-topic here. Run-on sentences are not specific to software technical writing. –  David Thornley Jun 23 '11 at 19:58
add comment

migrated from stackoverflow.com Jun 23 '11 at 12:03

This question came from our site for professional and enthusiast programmers.

5 Answers

up vote 5 down vote accepted

Not if I can help it :)

Think about it this way - what is the purpose of technical documents?

Right - to communicate something technical - and possibly quite involved/complex.

Now imagine you are listening to someone explain something to you that you are struggling to follow - they don't stop, they don't pause, information is flooding into your brain faster than you can take it in, you end up following nothing.

It's the same with reading - too much information without a break, and the reader will generally either skip it without having read it properly, or repeatedly read that sentence until they can finally hold it all in their heads at once and understand it.

Don't do this to your readers! Put yourself in their shoes - write it as you would wish to read it.

Short, succint sentences are best - you're not writing prose.

share|improve this answer
add comment

Unfortunately good writing skills appear to be rare among many technical people including programmers. The bonus is that with a little investment in improving your writing skills will make you stand out.

share|improve this answer
1  
+1 " good writing skills appear to be rare among many technical people" That's probably why it's not recognized as on topic and relevant. :-) –  Stephen Jun 23 '11 at 12:26
add comment

Consider this:

A single 40-word sentence that someone reads 4 times before comprehending it that too with some doubts and in the end the sentence is ignored because "there are more to follow"...

Another alternative:

Four 10-word sentences. 
Understandable in (at most) 2 readings. 
Reader's happy and of course, understands what you wrote.
share|improve this answer
    
My technical writing professor would tell me to write "Reader is happy ..." instead. This takes only one extra character. –  Job Jun 23 '11 at 15:13
1  
@Job would've written the same if we took that class togather –  KK. Jun 23 '11 at 15:34
    
I don't think any of those examples is grammatically accurate. –  TRiG Jun 30 '11 at 12:11
    
@TRiG now that you've mentioned it, I too think the same. But then I think they express what I wanted to convey. –  KK. Jun 30 '11 at 12:35
add comment

Is packing more technical information into one sentence better than creating many little sentences each with a little bit of technical information?

To some extent, this is a language dependent question. From the point of view of English, it's generally very poor practice to overload sentences although there is some more scope in, for example, German.

share|improve this answer
    
Interesting. Why is that the case in German? –  Sean Noodleson Neilan Jun 23 '11 at 13:46
    
Because their word formation and grammatical structure allows them to structure sentences differently to English and, additionally, pack a lot of meaning into single words that would take several to describe in English. –  temptar Jun 23 '11 at 14:08
add comment

Consider other ways of presenting the information to promote clarity. For example:

  • Try bulleted points

try using a picture

(I appreciate that pics may be hard to use in code comments)

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.