Hello,
This is more of a general query. I was wondering how a big project is being handled in respect of documentation. I saw GDD, Game pitch etc but how a big project should be documented (like project structure, functionality etc) so that team members (or new comers) can easily work together.
Thanks!
Depends on scope and project status.
If you are making an API all you have to document is function calls and variables they take / output they produce.
This is also completely useless to any programmer worth paying, as theyâll break apart functions themselves.
If you are documenting used tools, toolkits and pipelines, then you want to be as accurate as possible because everyone does stuff different.
And you can bet anyone worth paying will continue to do stuff however the h e l l they want to.
So thereâs basically no point in documenting pipelines either if you hire the right people for the job.
If you are making an Engine, then you want your documentation to be the furthest thing from Epicâs stuff.
First it has to be accessible.
So make a simple and custom website that actually works over mobile.
Second, fire anyone who f u cks the file format and generates unreadable pages.
Third, populate the pages with as much relevant data as possible, instead of filler text, opinions, and BS no one cares about.
Fourth,
When you adjust/fix anything thatâs changed by a new version, you invalidate pages or mark a version system.
Allowing people to access the actual OLD documentation as it was.
You can actually look at Blender docs for an example of decent work. Mind you, blender is going the epic way too, so maybe look at older doc releasesâŚ
.28 vs any Pre .28 is a good example.
The documentation infrastructure for large project is the most important part. Particularly if itâs public facing. Either make your own if you are good at websites, or hire a company to do a custom job.
I doubt you can rely on cookie cutter templates or WordPress fckups to handle one of the most sentivie things to your end usersâŚ
Thanks mate. You have pointed out some interesting things. I wonder how big game project is being handled as they develop them through long years and update always.
They donât document much of anything. Case in point being stuff like cyberpunk that tanks XP (and it was actually a really decent game for PC)
So for new comers entering into the development of an old project is like âBro, come on in, check by and run for yourself and build me this feature. thanks!â.
Recently we struggled as one of our project did not have enough documentations of it. So I was wondering this topic.
Generally speaking, if you hired the right person theyâll never ask stuff like âwhy is my bin folder not buildingâ and such.
I deal with that a lot too doing project management. Just hire better people and problem solved.
The first duty of any programmer is to be a problem solver⌠when you sleep at the wheel / ask silly stuff, refuse to google for your own answers⌠thatâs when I just fire them.
Well, that seems legit. Still there should be at least some documents. Just like you told that project size really matters. As much as it is feasible, making some documents wont hurt. Question is how to make it in our own style and no one can help here 
If itâs for internal purposes, just wack-a-mole it in word.
Itâll be helpful but not critical.
I came across this topic myself. I canât agree with other posts that no documentation is needed. Even when working alone on a project I document quite a lot. I use a mixture of inline code documentation and a tool called Whimsical (a free alternative could be diagramms.net) , which allows you to create diagrams / flowcharts and even ui or text-documents. Of course I donât create them for every aspect, but for keeping overall architecture and workflows in memory they are quite usefull.
Blockquote Question is how to make it in our own style and no one can help here
There are plenty of templates and guides around on what should be in a GDD.
Itâs something that can evolve based on otherâs documents e.g. Iâve added a MoSCoW breakdown a section on design pillars that the game will be based around.
However, one key rule to follow would be to make sure that someone with no design, programming or general games knowledge can read it.
Thanks @Rechi186 . Yes, I am also thinking of some sort of feature documentation (likely flow chart types) with inline documentation. 
Thanks @Kruul . Yes, templates of GDD will be a good starting point. But eventually I think we have to customize based on our project. No way around. 
Oh for sure. They can be a double edged sword to say the least 
Not sure what kind of project you are working on, but I recently finished an animation where the customer asked me to handle the source files with documentation.
It took me some time, but I made a Word file (as someone mentioned before), and tried to add as much images/screenshots as possible, mentioning the folder structure and where everything were (I kept the imported 3d meshes in one folder, materials and shaders and textures in another, blueprints in another, etc.).
All in all, I tried to keep everything as clear as possible, writing it as if I someone was teaching me the basics of UE for the first time, and started from the basics, as how the project is set up, etc⌠And clarified the possible errors that he might get along the way and how to solve them.
As I mentioned, it took some time but I think the time spent in it was worth it.
Try to gauge who the user will be, as if he/she has some previous experience with 3D, he might already know how to do some things.
Be that as it may, thatâs a paid request.
You didnât just spend valuable time you could have put elsewhere to make a living into it.
Anytime a client is willing to pay you should produce the best possible documentation you can.
That doesnât mean it will ever be needed by the client though. Or that they will ever even look at itâŚ
(Because sometimes, you would really hope they look at it)
Here is mine for example.
Some points.
Honestly, I use Word and the outline format.
I make sure I articulate the following:
After this, break down what you need to make, eg: a landscape or a critter, etc
What does this (and the other things) require? Sounds, a material(s), mesh(es), etc. Here is where a spreadsheet helps (and can easily translate to tables/csvâs for your game). Itemize what you need to build. I chose to break it down by item/thing/object on the rows and the columns were what mesh(es), etc I needed for each thing. Red, yellow, green (traffic-light) your way to update that matrix.
Iâd say it would depend on how often new people join the project and how large the project is. Canât speak for large development studios, but for small indie teams who often outsource or work with third parties Iâd say some documentation thatâs essential would be:
Top Level Application Description: What the project is and does from a users perspective. What the projects trying to achieve. Aesthetic styling, target levels for asset budgets quality and detailing. Game world background history and lore. Doesnât need to be more than a few pages but is also good for existing members to keep focus on the projects main objectives, or for sending out to any third parties or prospective new members to give a description of the project.
Use cases: How the user will use/interface with the application and actions they can perform. The main game menu states (Top menu, game setup menus, network lobbies) and in-game states (game setup, in-game, micro-games, tear-down). Also actions users can perform both in menus (menu items and options) and in game (how the user will interact with the game). This should just be top-level abstraction, so just a list of the states and actions with a brief description of what they are, what they do, and when they can be used. Again this is also good for existing team members as it keeps mission creep in check and for keeping track of what has and still needs to be done.
Structural Overview: A listing of your main classes and a very brief overview of what theyâre for, what they do, and the main classes they interface with (what uses them and who they use), a class or flow diagram would also be useful.
Class Descriptions: A more in depth description of each of the main project classes, the functionality they are responsible for and any major data structures they contain.
The design docs are useful for solidifying the top level structural outline of the project, clarifying the design, and highlighting things that might not have been thought of pre-implementation. Theyâre also super useful for new members of the team to have an overview of where to start looking in the code rather than being greeted by a wall of code and function names.
As other people have said, below top-level design documents, keeping functional, variable, and api documentation up to date is generally a nightmare and not worth it as you can spend twice as long documenting a function than coding it, then it will change the next week and someone will forget to update the documentation. Most large companies and projects auto-generate most of this now. If you keep the code itself well documented thatâs usually enough.
Documented Code: Seriously worth including good in-line documentation in your code both to remind yourself later and for newcomers. For complex algorithms or formulaic equations its a good idea to have a document somewhere referencing source materials, research, or description of the algorithm.
Another really useful piece of documentation is auto-generating call sequence and flow logs by embedding debug printouts into the code at the entry/exit point of each major function (just print out the function name, argument values, and any other useful data), and save the logs for later reference. Canât count the number of times this has saved me when a complex boot sequence has suddenly stopped workingâŚ
Initialisation Sequence
Function Flow
Netcode Flow
@Mach45 has a good example there.
Others who scoff at documentation for various reasons make valid points, but it begs the question about how long theyâve been developing or working on team-based projects, or even as a lone wolf on projects of different scopes.
Personally, I believe documentation is important. Depending on the project and team size, what this documentation ends up being can change. For example, small projects as a lone wolf might introduce a âreadme.txtâ with a quick overview and helpful references, and perhaps a ânotes.txtâ that acts as a dumping ground for ideas, reminders, etc. Perhaps even a âtodo.txtâ if you arenât using any sort of task/project management tools.
On medium-to-large scale projects, documentation becomes paramount. Outlining vision/goals, setting out semantics and methodologies, referencing tools and pipeline flows, establishing contact/communication processes, and so on all contribute to keeping a team and project educated and on track. It reduces feature-creep and scope-stray.
Saying that dealing with documentation is a waste of time, says something about oneâs character⌠Personally Iâd rather document a process or semantic point once, than have to remind others and myself consistently. That is a waste of time, due to laziness and wisdom to have properly documented from the start. Some people have the approach to âjust-make-it-workâ and âjust-get-it-doneâ, and donât have the trait of building solid foundations that last and stay healthy⌠And sometimes, thatâs just fine.
Well written documentation has other benefits- especially when done well. Various documents can translate to game guides/instructions, game communities love to tear apart documentation youâve made public (perhaps for modding purposes, or purely out of curiosity), and your documentation can aid greatly in getting newcomers up to speed. Not to mention the benefit of having a historical reference should you personally step away from your project for some time, and (like myself) have the memory of a banana buried in the Antarctic.
Having worked in the technical industry for 2+ decades, and on several game projects⌠Any professional or serious indie would laugh at the idea of nixing the task of documenting. I canât tell you how many curses Iâve heard come out of my mouth and the mouths of others, when coming into a project that has no documentation, and time (wasted) has to be spent figuring things out.
20 solo human hours of writing documentation, is far less of a time sink than 1,000 combined human hours of stumbling through the dark and constantly repeating yourself.