Plan for Rick Overman
by Rick Overman · 03/12/2004 (1:18 pm) · 9 comments
We have been having a fun conversation about a wiki for GarageGames over on the forums and I thought I should repost a few highlights here.
We are feeling the growing pains I have seen many company forums suffer. Eventually it doesn't matter how good or bad your search capabilities are because your forums are filled with old cruft that doesn't pertain, repeats because no one searches before they post and casual conversations that would have been better held on IRC.
Several people have asked about starting a wiki (we have been thinking it too). Wiki's generally solve the casual conversation problem but they suffer from the same old cruft problems. Part of the rational for the wiki was for documentation which I am opposed to. We already have a great documentation project underway and what we don't need is two competing projects. But I could see a good split where one (docbook) is formal documentation and the other (wiki) is informal "how do I..." type documentation.
We have a bit of time before I put something in place (see my schedule below) so I would like to keep the forum discussion going.
--Rick
Here is what my extremely abbreviated to-do list looks like:
1) Update the shopping cart and back-end sales/accounting system to support shipment of physical items (ie t-shirts, on demand CD burning, on demand Printed Manuals, etc...). In progress.
2) Configure and deploy a new web server (to replace our little engine that could). This includes several behind the scenes site changes including upgrading to Apache2 and Gentoo.
3) Next revision of documentation should be ready to post. This is a big milestone -- all existing documentation will have been updated and ported to DocBook. The page count should be around the 250-350 mark (not including the 2000 pages of DOxygen code level does).
4) Configure and deploy an ad server for GarageGames (on new web server). No GG is not going to be covered with crappy external ads, but rather we want to use it to promote our own games on our site. Also gives us the ability to serve ads to affiliate and fan sites.
5) Then the big decision which to do first: the wiki or a blog. We have wanted to move at least the GG Staff and possibly others to a more traditional dedicated blog format. Jeff, as with the rest of the GG team, are a fountain of information and we just need a way to get the word out. The .plans kinda work but they are buried on the site, no continuity, to categorization, each post is an island not a chain of thought and .plans are so 90's ;). As a result none of us post often enough. A blog would give each person a dedicated channel to get the message out, rss/atom feeds and discussion.
We are feeling the growing pains I have seen many company forums suffer. Eventually it doesn't matter how good or bad your search capabilities are because your forums are filled with old cruft that doesn't pertain, repeats because no one searches before they post and casual conversations that would have been better held on IRC.
Several people have asked about starting a wiki (we have been thinking it too). Wiki's generally solve the casual conversation problem but they suffer from the same old cruft problems. Part of the rational for the wiki was for documentation which I am opposed to. We already have a great documentation project underway and what we don't need is two competing projects. But I could see a good split where one (docbook) is formal documentation and the other (wiki) is informal "how do I..." type documentation.
We have a bit of time before I put something in place (see my schedule below) so I would like to keep the forum discussion going.
--Rick
Here is what my extremely abbreviated to-do list looks like:
1) Update the shopping cart and back-end sales/accounting system to support shipment of physical items (ie t-shirts, on demand CD burning, on demand Printed Manuals, etc...). In progress.
2) Configure and deploy a new web server (to replace our little engine that could). This includes several behind the scenes site changes including upgrading to Apache2 and Gentoo.
3) Next revision of documentation should be ready to post. This is a big milestone -- all existing documentation will have been updated and ported to DocBook. The page count should be around the 250-350 mark (not including the 2000 pages of DOxygen code level does).
4) Configure and deploy an ad server for GarageGames (on new web server). No GG is not going to be covered with crappy external ads, but rather we want to use it to promote our own games on our site. Also gives us the ability to serve ads to affiliate and fan sites.
5) Then the big decision which to do first: the wiki or a blog. We have wanted to move at least the GG Staff and possibly others to a more traditional dedicated blog format. Jeff, as with the rest of the GG team, are a fountain of information and we just need a way to get the word out. The .plans kinda work but they are buried on the site, no continuity, to categorization, each post is an island not a chain of thought and .plans are so 90's ;). As a result none of us post often enough. A blog would give each person a dedicated channel to get the message out, rss/atom feeds and discussion.
#2
So if you go the wiki route, I suggest some kind of moderated wiki, I'm sure there is such a thing out there.
Not sure what form that would take though.
03/12/2004 (2:47 pm)
I think in general, a wiki style format works. But you have to have some level of moderation, or non-arbitrary posting. I always liked the open format, but dislike the security and fact that ANYONE can post, even if its rubbish.So if you go the wiki route, I suggest some kind of moderated wiki, I'm sure there is such a thing out there.
Not sure what form that would take though.
#3
03/12/2004 (4:45 pm)
I still want a //DMM: FIX! t-shirt 
#4
As for blogs, I think it would be good if the GG folks and associates get that functionality. Everyone can benefit from that, instead of the .plans getting buried by less informative ones.
03/13/2004 (9:05 am)
Docbook sounds great. I'm still scared of the 2k+ page document my Doxygen generated(I swear I've seen it standing over me while it thinks I'm sleeping sometimes ;)As for blogs, I think it would be good if the GG folks and associates get that functionality. Everyone can benefit from that, instead of the .plans getting buried by less informative ones.
#5
It just feels like moving to yet another format, in this case Wiki, is like splitting hairs with the efforts we've made with DocBook. DocBook in itself, is mostly just a conversion of the docs we have now into the DocBook format so it seems by adding Wiki to the mess we are just adding another layer of redundancy and complexity that we just don't need.
I'm not all that familiar with Wiki, so excuse me if what I say is not true, but I just don't see anything that Wiki can do that DocBook can not. If people are so eager to help with documentation then I believe the best thing that can happen right now is for them to jump onto the DocBook format which GarageGames has so far adopted as the utility of choice for documenting the engine and the process of working with the engine.
If everyone would just gather around and support one main documentation utility I believe we could get things done much faster then spending our time discussing the flavor of the month in documentation formats.
03/13/2004 (2:53 pm)
I'd just assume stick with docbook. I'm on spring vacation right now, for a week, but when I get back I'll probably start discussing this further.It just feels like moving to yet another format, in this case Wiki, is like splitting hairs with the efforts we've made with DocBook. DocBook in itself, is mostly just a conversion of the docs we have now into the DocBook format so it seems by adding Wiki to the mess we are just adding another layer of redundancy and complexity that we just don't need.
I'm not all that familiar with Wiki, so excuse me if what I say is not true, but I just don't see anything that Wiki can do that DocBook can not. If people are so eager to help with documentation then I believe the best thing that can happen right now is for them to jump onto the DocBook format which GarageGames has so far adopted as the utility of choice for documenting the engine and the process of working with the engine.
If everyone would just gather around and support one main documentation utility I believe we could get things done much faster then spending our time discussing the flavor of the month in documentation formats.
#6
I don't think they're mutuall exclusive - you could easily write a wiki that used docbook for formatting instead of wiki-markup.
03/13/2004 (5:09 pm)
A definition: Wiki is a means for organizing data, independent of format. DocBook is a format with some organizational structure around it.I don't think they're mutuall exclusive - you could easily write a wiki that used docbook for formatting instead of wiki-markup.
#7
Sounds like great plans for the community!
03/13/2004 (11:33 pm)
You guys are so Organized and stuff :)Sounds like great plans for the community!
#8
I am sure that the code for this is probably available. I would also add a couple of features:
1) Ability to turn off adding new comments
2) Ability to pull all the comments out so that documentation can be updated
3) Redeploying the documentation removes all the old comments
This way the documentation can be updated periodically and old comments will not be around to confuse users.
This is just a thought I had, it would have to be thought out further. I don't know much about DocBook, but I'm sure it wouldn't be hard to get the data into a system like this.
And hey, if it means better documentation, I would be willing to help make the system. I am an asp web developer, but I have done some php work in the past.
03/14/2004 (6:54 am)
The PHP documentation has a nice feature where users can leave comments in the documentation. This way the community can post corrections and clarifications.I am sure that the code for this is probably available. I would also add a couple of features:
1) Ability to turn off adding new comments
2) Ability to pull all the comments out so that documentation can be updated
3) Redeploying the documentation removes all the old comments
This way the documentation can be updated periodically and old comments will not be around to confuse users.
This is just a thought I had, it would have to be thought out further. I don't know much about DocBook, but I'm sure it wouldn't be hard to get the data into a system like this.
And hey, if it means better documentation, I would be willing to help make the system. I am an asp web developer, but I have done some php work in the past.
#9
03/14/2004 (12:49 pm)
So is the full-text search for the forums ever going to happen? I still think that would be very useful - even if some of the information is out of date. The same is true for usenet postings - but you can always sort the results by date and look at the most recent posts. I find that searching newsgroups on google is one of the best tools in the world for getting answers to all kinds of things. I would think that being able to search the GG forums would be a catalyst in the same way for Torque developers. 
Associate Justin Mette
Default Studio Name