Technical Writing??

    This site uses cookies. By continuing to browse this site, you are agreeing to our Cookie Policy.

    • Technical Writing??

      Hi everyone, I'm a college student aspiring to be a game programmer and was wondering if I could ask any software engineers or game programmers out there a quick question. But before that, I love the book Mike, it's awesome and very inspiring!

      To the question: I have a technical writing class I'm in right now and an assignment was to ask an engineer about the importance of writing and communication in their field, types of writing that will be expected to produce, potential audiences for the writings, and the nature of the writing medium (I'm guessing electronic =P ). I decided to ask here to any programmers since it would help me know what to expect once I'm out of college and out on the job in terms of written communication in a software development environment.

      Thanks for any responses =D
    • RE: Technical Writing??

      I know i'm not the person you want responding to your post but i have a suggestion. Comments in code seems to be teh perfect example of writin communication in the programming field. How do you expess the meaning of code or how do you explain what you were TRYING to do even if you failed horribly? Comments. Just think about it.
      .Code
      push you ; haha!
    • RE: Technical Writing??

      On my small team, it's usually scrawlings on whiteboard and random pieces of paper for intrateam communication, but we write documents detailing each program (or modification) before we start.
      -Larrik Jaerico

      www.LarrikJ.com
    • I've found that the quantity and quality of technical documentation varies greatly from company to company. Some companies have very little, other companies have huge amounts.

      At Super-Ego Games, we have quite a bit of documentation, mostly due to the fact that we have two offices. All the artists, sound gods, and production staff are in New York while all the programmers and here in San Francisco. This creates a bit of a communication gap.

      Most of our documentation is in the form of an internal Wiki which we use to communicate everything from policies like the company programming style (bracing policy, naming convensions, etc), design documents, episode Visio diagrams, etc. Anyone in the company is welcome to add pages or modify existing ones (within reason) and it serves as a sort of living, breathing company handbook / design document. We do have more official design documentation which is linked to from the Wiki, but these are typically for investors and other outsiders.

      That having been said, I feel that we are weak on the details. You can go onto the Wiki and read all about the concept behind the UtilEcon system (a system for dealing with the transaction of needs/wants and satisfiers; basically the NPC AI system), but you'll never find a class diagram for it, nor will you be able to makes heads or tails of the half-dozen or so XML files that drive the UtilEcon engine. For that, you'll need to talk to the lead designer who wrote it (or me, since I've inherited it :) ). Or what about the opponent AI? The programmer who wrote that is gone, so in order to change anything, I would have to spend a large chunk of time just figuring out what he did.

      Hope that helps. Let me know if you want any further details or have any questions.

      -Rez
    • RE: Technical Writing??

      Originally posted by DarkPenguin
      I know i'm not the person you want responding to your post but i have a suggestion. Comments in code seems to be teh perfect example of writin communication in the programming field. How do you expess the meaning of code or how do you explain what you were TRYING to do even if you failed horribly? Comments. Just think about it.


      Most game programmers I've work with: "Comments? What are those?"

      (sigh) I couldn't agree more.... That UtilEcon system I mentioned in my previous post had about 4 comments spread across the six or so source files that make it up. It took me like two or three days of pouring through hundreds of lines of code just to decipher what the hell he was doing. I've been sprinkling comments in there as I go, but man.... talk about a pain in the ass. At least he uses good names for variables, functions, classes, etc or I would have had to hurt someone.

      Then again, I guess it served as a crucible of sorts.

      End rant.......

      -Rez
    • RE: Technical Writing??

      Heh. I got an answer:

      I wrote a book!

      Seriously, writing is extremely important, and programmers will do quite a bit of it.

      I write these kinds of technical writing in my job:
      - Project proposals for clients, usually in PDF form.
      - Answers to questions from all walks - usually in forum posts (duh), email, and sometimes more formal documents.
      - Critical analysis of technology or project plans for the people I report to, usually in PDF form.
      - Technical Design Documents for clients, always in PDF form.
      - Presentations on all manner of subjects, always in (bleh) Powerpoint.
      - Whitepapers on all manner of subjects (10 pages or so) for conferances, always in PDF form.
      - Books for people like you! Also in PDF form.

      I always write the big stuff in Word, edit and review with Track Changes on, and convert to PDF when it's done.
      Mr.Mike
      Author, Programmer, Brewer, Patriot
    • RE: Technical Writing??

      Mike, I'm curious.... do you do much coding in your current job anymore? If not, do you find that you miss being being one of the grunts on the front lines?

      -Rez
    • Wow, thanks for responding so quickly everyone =D

      In response to Rez and Dark, I completely hear you on the commenting issue. I had a teacher that actually deducted major points for under-commenting, so it's been driven into me to comment every now and again and to make comments like mini-instructions on what the code is doing. I actually had to grade a friend's program one time, and I couldn't help him fix an error and spent an hour just trying to understand what his code was doing before I could help him. Thankfully it wasn't a huge project like you guys do.

      And thanks for the heads-up with that Track Changes thing Mike; I actually had no clue about that feature of Word. Also I'm happy to see that almost everything you bulleted, such as project propals, technical design documents, whitepapers, etc, are lined up in the near-future for the course.

      Again, thanks for the replies everyone =D
    • RE: Technical Writing??

      Originally posted by rezination
      Mike, I'm curious.... do you do much coding in your current job anymore? If not, do you find that you miss being being one of the grunts on the front lines?
      He lights up like a kid in a candy store whenever the programming team mentions that they may not have enough bandwidth to cover the third person camera code.

      KoloRahl, a programmer who can communicate with both, other programmers and non-programmers, with equal clarity is much more valuable than a brilliant programmer who expects people to just figure it out. I've done a lot of instructional writing for the level designers, so that they would have written instructions on how to use a newly coded feature and things to watch out for in using that feature.
    • RE: Technical Writing??

      Originally posted by KainHe lights up like a kid in a candy store whenever the programming team mentions that they may not have enough bandwidth to cover the third person camera code.


      Heh, I figured as much. ;)

      -Rez
    • RE: Technical Writing??

      I don't do much coding anymore - but every now and then I'll pick up a special project at work or even on my own to keep my skills from fading.

      And yeah - there are things that I miss about being a staff coder - but there are rewards I get being a studio manager that a staff coder doesn't get. I guess in the end it all equals out.
      Mr.Mike
      Author, Programmer, Brewer, Patriot