Before you read this document, please bear in mind that I am not a formal member of the development team and that many of the comments may be redundant as the result of my looking in on the project's development from the outside rather than knowing about it in detail from the inside.

Having said that, I have been involved in the development of some reasonably large and complex projects and hope that my comments may prove useful in helping the project to move forward faster and more smoothly.

Documentation

In spite of a notable lack of good documentation, it is clear that the devs currently working on the PS project are sufficiently familiar with its innards that the project is moving forward at an unusually rapid and reliable pace.

However, the project is still also clearly at a relatively early stage of development in several senses

• The world itself is still very small in comparison to the worlds of complete MMORPG's and so a vast amount of content can be expected to be added before the project is considered complete.
  • It is obvious that much more territory will be added before the game reaches its conclusion (if we assume that any MMORPG ever really does have a conclusion).
  • In the implementation of that additional scenery, it is fairly obvious that many functional aspects of the landscape will first have to be implemented. Obvious examples are moving doors, containers, locks and vehicles.
  • There currently appears to be no effective documentation on how the world is constructed, how its 'zones' are created or organised or how the scenerey is and should be fitted into that.
  • If PS ends up comparable to other MMORPG's, and all current indications are that it may well prove better than the average game, then developing, constructing and maintaining even just the simple world scenery is likely to be a very large task.
  • Bearing that, and the fact that the project is essentially still at a relatively early stage of development, it is clear that clear and well written documentation on how to develop further scenery will be extremely necessary if the project is going to be able to cater to the massive amount of interest that it is receiving from people willing and able to contribute to this part of the project.
  • More importantly, if the project is going to continue to develop at a reasonable pace as the amount of ground that it covers increases, then the ability to cater to those willing to contribute to the project will be an extermely important aspect of its progress.
• The scope of the game engine itself is already very great, but is likely to increase tenfold before the game is considered relatively complete.
  • Even at present, the task of familiarisation with the program code for a new developer joining the project is probably an extremely difficult one. The difficulty of this is surely going to increase exponentially as the scope of the project and the extent of its code does, with the result that it will be increasingly difficult for new developers to integrate themselves in to the development of the project, even while the project has a greater and greater demand for good new developers.
  • There appears to be no documentation available at all on the general layer and module model of the project or on what the conceptual content of those is and should be.
  • There is no documentation available either of the classes used in the project or on the methods and functions that implement the game's functionality.
  • While this lack of documentation may not currently be a vast impediment to new members contirbuting to the development of the project, it is clearly not an insubstantial one and even at that is one that it going to increase greatly as time passes.
• The documentation on the build process, while adequate for those people who are also proficient in system setup, is extrememly inadequate for those people who are purely programmers, designers or suppliers of media.
• These specialist talents, talents that the project clearly needs and will clearly soon need in much greater abundance, are going to find the porocess of joining and contributing to the project more and more inhibiting as time passes and the amount they have to learn before they can make a genuine contribution increases.

The above are merely a gloss of the general issues that it seems likely that the PS project will soon have to face with much greater impact on the progress of the project than is currently the case.

As far as I can see, there is vast general interest in PS among development talent and the lack of good documentation is a serious impediment to the ability of the project to continue to progress at its current rapid pace.

To comabat this problem, I suggest that the following startegy may help to ensure that the project lives up to the expectations and aspirations that we all have of it.

Build Documentation

• The current documentation is scattered and generally indaequate. Easy proof of this can bee seen in the number of times the same questions are recurrently answered by development personnel on the PS forums.
• There should be a sticky post in the Development Deliberations forums that gives a clear outline and guide to build instructions on each of the platforms that the project can be built upon.
• Obviously that documentation should be echoed in the source distribution.
  • Those support libraries and their versions that are necessary before the game itself can be built should be clearly and fully recognised and those places where those libraries can be obtained should also be clearly detailed.
  • Whether or not support libraries are optional or not should be clearly documented and the means of not optionally not using them should be clearly outlined and specific to each build environment.
  • A recommended, default source tree for the project should be clearly specified and the content and purpose of each branch should be clearly described. Where possible, the source tree should be platform independent.
  • The full build source tree for the project should be included as distribution limitations permit should be in the CVS - and/or complete CVS checkout of all required sources should be scripted to whatever extent each platform allows.
  • Compilation instructions should be clear and detailed with respect to each supported patform and environment. Preferrably, a skeleton template should be produced so that people who port the project have a consistent framework to work to in documenting how other people can follow after them.
  • The structure of the project should be clearly and fully documented so that new developers can quickly find out how to begin contributing their own efforts and how to integrate those efforts in with those of other developers.
  • Each class, method and function/procedure should be clearly documented by hand in overview and outwith the code proper as to what its purpose is and how it works.
    Automatic documentation is not a good way to help people get to grips easily with a project that they have never worked on before and is only really useful for enumerating a project's functionality rather than explaining how to make use of it.
  • All code should be briefly but clearly commented as to its purpose and manner of operation. Such comments should preferrably include pointers to external documentation that describes relevant models and protocols more fully.
  • Every individual programmer, artist, sound technician and quest designer should be asked to take on responsibility for clearly documenting the work that they contribute.
  • As a developer myself, I know how damned annoying it is to 'waste' two out of ten hours coding by documenting the stuff I have written, but I also know that having that documentation can save me days of time spent trying to work out what this code all does and how it has been put together.
    At the very worst, taking an extra 30 mins to make sure that my code is well commented has saved people I have worked with hours of time trying to muddle out code that is clear to me but very obscure to them.
  • To put this issue in perspective, let me ask you a question. Are you a fluent programmer?
    If you are then you probably understand 50-75% of the code you read the minute you look at it. But what you understand is how it works, not exactly what it does or where it is coming from.
    The ten mins that you or someone else takes to comment their code can save you an hour or two of working out what exactly they are doing, what other code their code is interacting with and help you get a much faster insight into how all the parts of the project that you are working on fit together.
    Take another 30 mins to write a few paragraphs on what your design decisions were when you put the code together and to overview its general mechanisms and you really are saving yourself or someone else days of effort going through the code to come up to speed on what you wrote six months ago or to become familiar with what they have never seen to start with.
  • Documenting Quest Design is not an easy job. Most people would sort of document the NPC's they introduced and the quest objectives and that would be their doocumentation.
  • Quest Design is the most important thing that the user gets to enhance their sense of ingame atmosphere when they play they game.
  • As a designer, you should be documenting as clearly as possible any cues that will help the person following on from your work where you came from and what your inspirations were.
  • In particular, it is all very well to say that your NPC character conforms to the Xzexial race in the context of the game that you are designing. But you are dealing with human beings from the planet Earth and they are not that likely to be familiar with that race. Remind them that the Xzexial race is similar to the Chilean Gaucho's and give them a brief description to inform them if they do not already know that the Gaucho's were basically part of a herding culture with facility in horse riding and dealing with cattle. The NPC that you start as a minor character may end up being a very major character once the world that you are helping to build has been developed.