GPGT Postmortem - Part 3 of 3 (Lessons Learned)

Synopsis
After much deliberation, I have decided to ignore the trend to write a postmortem using the standard 3-3-3 format (three things that went wrong, three things that went right, and three things learned). So, consider yourself warned, this postmortem is a little long.

I am writing this postmortem for the community and for myself. It is my hope that those who read it will be able to take away some useful bits of information.

This postmortem contains the following three sections:

1. History Of GPGT - In this first section of the postmortem I traverse the entire history of this project, highlighting the important events that occurred along the way. The purpose of this is to show how a whim and a hobby can turn into something more serious.

2. Project Analysis - In this second section of the postmortem I will do a detailed analysis of the project, providing a more formal look at the different parts of writing this book. I will discuss such details as schedule, budget, tools, etc.

3. Lessons Learned - In this third and final section I examine some specific things that I learned along the way.



Part III - Lessons Learned *** WARNING *** No Pictures, See part 1 for that :) *** WARNING ***
This final section will be a free-form list of things that I learned while writing the guide.


Limit Your Scope
If you are writing a book or other document. Limit your scope from the start and be sure to keep to that limit. I started GPGT as an open-ended project and got bitten by major feature creep.


You're Not Going To Get Rich
Boy. Jeff was so right. No single book is going to make you rich. The trick is to create a steady flow of products, each of which contributes to your bottom line incrementally. If you can only afford the time to work on one project, and if you need to make your living from that project, then I don't suggest writing a book. You'll probably starve long before you finish it. However, if you can afford the investment of writing a book, then by all means do so. Why? Because, books have the following nice properties:

==> Relatively long life. If you can refresh a book and publish new revisions, you can benefit from your initial investment of time over the long term.

==> Can Be Turned Into Franchise. No, I don't mean a literal franchise. What I mean is, often written material can be adopted to other purposes. Thus, you may be able to re-use your written material to create other products.

==> Name Recognition. Most people (not all) still tend to recognize that writing a book is no simple task. So, finishing and publishing one cannot hurt your reputation (as long as you do a good job of it), and a good reputation is one of the pillars of success.


Collaborate Using a Private Website
Early on in the project I created a private site where I could post the latest versions of chapters and supporting materials. This allowed any reviewers with access to download the materials when they wanted to. It also served as a pseudo-backup mechanism. I ended up having more than one site by the end of the project, each one dedicated to a different set of reviewers/consumers of the draft GPGT materials.


Create Your Own Base 'Kit'
If you are writing about a programming topic or another topic that requires a starting point, then provide that starting point. In my case, I ended up relying on the 'FPS' Starter Kit as a starting point and this got me into real trouble at the end of the project. This happened because the kit itself changed from version 1.2 to 1.3 to 1.4, AND because there are slight variances in the OSX and Windows versions of the Starter Kit (as supplied in the demo).
Hindsight tells me that I should have created my own starter kit and used it exclusively.


GPGT Lesson Kit
Although I didn't create my own base kit, I did have the GPGT lesson kit. I created this application so that I might create samples in these categories: GUI, Interface, Scripting, and 3D lessons. The kit itself was designed with a tool kit of scripts and predefined lesson file formats. This allowed me to easily create a new lesson and simply drop it into the kit, knowing that it would be properly loaded and displayed to the user. This had the added benefit of allowing me to provide new lessons after printing.


Know What You're Going To Write Before You Write It. #1
By this, I simply mean know your topic matter BEFORE you write. I started this project on a whim and while I was still new to the engine. Thus, I ended up re-writing sections later when I learned of new or different engine features which required a different approach to documenting them. In some ways, this actually helped this particular document, but the overall effect was a significant slow-down.


Know What You're Going To Write Before You Write It. #2
No, I'm not really repeating myself.

This time, I mean you should decide what you want to write about BEFORE you write it. This may sound counter-intuitive at first, but what I am really saying is, to plan your book out before you commit any words to paper. This is not an easy process and you should expect to change your mind about organization later, but if you start without a plan, you will regret it.


Stick To Your Plan.
I just said that you should expect change and that is still true, but be sure that you only accept small changes. If you make broad changes to your plan, you will likely waste a significant amount of time and effort.


Know Your Tools.
Be sure to learn how your writing tools work before getting too far into your project. For example, if you are using Open Office, learn how to use Master Documents and Templates. Also learn how the formatting system works. Although I don't encourage to you to pursue final formatting decisions in the beginning of your effort, I do suggest that you set up a custom set of formatting rules in the form of a template and then use that template for all of your documents. Later, when you want to reformat your documents, you can do so by modifying the template instead of manually modifying every chapter.
Also, if you intend to use Open Office to generate your Table Of Contents and Index, learn how these features and the concordance import features work BEFORE you start writing. You can certainly do this later, but learning how to set up for an index in advance will save you a ton of time later.

About The Table Of Contents (TOC)
If you are using Open Office, I do suggest that you use the built in indexes and tables feature to generate your TOC. This feature works perfectly well. One thing though. Be sure to generate them with the 'Protect against manual changes' feature disabled.


About The Index
Regardless of what tool you are using to write your book I have these suggestions:

1. Do not use an external tool to generate your index or a concordance file. The effort required to do this is equal to or greater than doing it manually.

2. Do not use a concordance file import mechanism. In all but the simplest cases, this will generate a over-sized index that is next to impossible to trim down.

3. Plan for your index as your write. By this, I mean mark keywords and sections for inclusion in your index as your write, or during your final copy-edit session. Either will work, but the prior is best. It is best because when you are writing about a topic you are often in the proper mindset for generating the tag to go with your topic. If you do it later, you will have to ask yourself, "When someone is looking for this information, how will they be thinking about it? What is the best way to label this so they can find it?"

I tried all of the above methods for creating my index and found the latter to be the most sensible. However, because I did create my index last, it suffered for my lack of imagination at the time, and for the extreme time crunch I was under.

Believe it or not, it took me over a week to create the current GPGT index.


Use Test Readers From The Start
I was fortunate enough to have an entire class of test readers (Michael Rogers CS481 class at Millikin University) reviewing my material while trying to use it. This was extremely useful. The bottom line is, there is no way, after reading and re-reading your own materials for the 15th time that you will catch the same errors as a new reader.


About Art and Assets
I got some good advice from Joe Maruschak and from others while writing my book and while working on the game prototypes that go with it. A summary of this advise would be:

==> Use placeholder art until the very end. - In other words, do not bother creating superb art assets (or illustrations) until the underlying book/game is done. Why? Because, changes in the book/game may very well require changes to the art, thus wasting effort.

==> Use grayscale for all assets until the asset is finalized. - This is similar to the placeholder art idea, but the differences is that by using grayscale textures/illustrations for all non-finalized assets you can clearly see what parts of your book/game are not done yet, or at least have not made it through final approval. Also, and Joe pointed this out, when you show a demo or prototype and the art is grayscale, folks will be more accepting of changes that come later. i.e. They don't form attachments to specific assets and they expect change.

Lastly, I have discovered that while draft writing, it is best to skip art entirely, and in those cases where a placeholder is absolutely needed, just sketch something by hand, scan it, and import it. Unless you're a whiz artist (which I'm not). Don't even touch your art program(s).

Hall Of Worlds - For Gamers
EdM|GPGT