2

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?

3
  • 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, 2011 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, 2011 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. Jun 23, 2011 at 19:58

5 Answers 5

5

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.

0
3

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.

1
  • 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, 2011 at 12:26
1

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.
4
  • My technical writing professor would tell me to write "Reader is happy ..." instead. This takes only one extra character.
    – Job
    Jun 23, 2011 at 15:13
  • 1
    @Job would've written the same if we took that class togather
    – KK.
    Jun 23, 2011 at 15:34
  • I don't think any of those examples is grammatically accurate.
    – TRiG
    Jun 30, 2011 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, 2011 at 12:35
0

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.

2
  • Interesting. Why is that the case in German? Jun 23, 2011 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, 2011 at 14:08
0

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)

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