Technical Writing & Documentation

Started by
4 comments, last by Khaiy 12 years, 8 months ago
Hello I hope this is the right forum to post this in as it has "Writing" in the title, lol

As a Developer/Technical Person I've found myself over time very lacking in the writing GOOD documentation to some of my engine/game designs. Keeping this topic short, I basically want to improve my writing skills, cause alot of times I feel like I write in a way only I could understand, or someone else who thinks like might would be able to. Does anyone recommend some material, or maybe excersises I could do in order to improve my skills, I thought about taking writing classes in the city, but honestly I dont feel like travelling or spending the money. If anyone here is a good writer and is willing to mentor, I'd be willing to do a quid pro quo type scenario for any time given. Thanks in advance.
Advertisement
Nev,
Your post shows your problem. Your sentence structures are convoluted, and your spelling is poor ("cause alot of times I feel like I write in a way only I could understand, or someone else who thinks like might would be able to"). You need classes. You really do. And you can practice in Word. Turn all auto-correct features off, and work very hard at understanding what causes all the squiggly underlines your writing generates. Take classes, and practice, practice, practice.

-- Tom Sloper -- sloperama.com


Nev,
Your post shows your problem. Your sentence structures are convoluted, and your spelling is poor ("cause alot of times I feel like I write in a way only I could understand, or someone else who thinks like might would be able to"). You need classes. You really do. And you can practice in Word. Turn all auto-correct features off, and work very hard at understanding what causes all the squiggly underlines your writing generates. Take classes, and practice, practice, practice.


Thanks, I know thats what I need to hear, I Like the MSWord Idea, I'll be giving it a try, I know this is something Ill have to practice, but where should I even begin? I would need something to write about, any recommendations on finding topics to write about? As for classes I would like to take some in the future, but they are somewhat of an inconvenience for me in my current situation, but I don't want to wait a couple of months for some of my time to free up to improve my writing abilities, I would like to be able start as soon as possible. I have however (after this post) started looking into online writing classes maybe Ill be able to find something good there. Thanks again.

[EDIT]
I found this website Ill probably be giving a try, these two classes look promising
1.Grammer & Mechanics
2.Form And Composition
Thoughts on the subject matter for my needs?
but where should I even begin?

Begin by just doing it. Stop asking helpless questions. Know what you need to accomplish, and you'll know what you need to do.

-- Tom Sloper -- sloperama.com

You could try teaching yourself how to diagram sentences:
My link

If you are aware of the kinds of structures sentences can have, you can think about which types to avoid because they are difficult to read.

I want to help design a "sandpark" MMO. Optional interactive story with quests and deeply characterized NPCs, plus sandbox elements like player-craftable housing and lots of other crafting. If you are starting a design of this type, please PM me. I also love pet-breeding games.

Your biggest issue (to my eye, at least) is that you have a weak grasp of what makes up a valuable clause in a sentence. Lots of clauses nailed together by commas are like a train wreck hurtling at your readers' brains. It doesn't matter what else you do, because a run-on sentence makes it nearly impossible for a reader to grasp your meaning. This effect increases along with the length of the sentence.

Writing is more art than science, but if you want to write technical documentation you will have to stick to rules of grammar, syntax, and punctuation more than the creative writer does. You will have to learn the basic formal rules of language, but overall your focus should be on composition rather than the (endless and generally ignored) intricacies of grammar. As a technical writer, you will want to focus on precise use of vocabulary, clear separation of ideas, and strong organization of/between paragraphs.

Careful word choice will help you to express your ideas more succinctly, which will relieve some of the comma abuse and get rid of the pressure for circumlocution. Clear distinction between ideas will help you divide different ideas into different sentences, or if they are truly related enough, different clauses of a single sentence. Intra- and inter-paragraph organization will help you to convey your broader ideas effectively from your much smaller and more specific sentences.

The classes you linked look like they would be useful to you, but I'm sure that you could find some free resources online in the meantime. And my best recommendation is that you read books. Avoid pop literature, which tends to play a bit loose with quality. I can recommend the Rama books by Gentry Lee. The writing is strong from a technical perspective, even if the characters' dialogue often reads like stereo instructions. Come to think of it, any hard sci-fi books would probably be similarly good.



Anyways, just write whatever you can for now. It doesn't matter what it is just so long as you do it thoughtfully. Try to get exactly one idea per sentence at first (no commas), and try to make each sentence as clear as you possibly can. The meter will be bad, but if nothing else it will help you to separate organizational concerns from grammatical/syntactic ones.

And don't let Tom scare you off. You do need some review of the basics, but feel free to ask questions here in this forum.

-------R.I.P.-------

Selective Quote

~Too Late - Too Soon~

This topic is closed to new replies.

Advertisement