Creating documentation for Modders

[ahmed007boss]

This pull request adds a first set of documentation files and starter pages

What is included
ModdingDocs - a starter collection of pages that explain BodyBehaviors. Those pages set the expected layout and tone.
community driven code of generals

• Notes clearly state that the branch is a community upgrade built on Retail 1.08/1.04.
• Contributor structure, version labels but also review steps remain unchanged.
• Documentation must stay uniform - all pages share the same wording rules, property layout, enum style and template use.

Why

• The project needs a single, consistent starting point for community written documentation.
• The wording must match the open source code of the project any new feature or fix added need to known to modders should be updated in documentation
• New contributors should be able to open the repository and follow the exact format from the first edit.

Scope

• Only documentation changes - no gameplay or engine code changes.
• This is an early seed - additional pages and document reviews will arrive in later pull requests .

Follow-ups

• Add more body or behavior detail pages and link them together.
• Once maintainers approve, add a prominent link from the root README to those docs for easy discovery.

Notes
The pages are intentionally incomplete at this point. The pull request only sets the format also review process.

[xezon]

Perhaps this should go into the GeneralsWiki Repo?

Not sure if there are any Doc maintainers left currently. User DevGeniusCode lead the overall doc effort previously.

[ahmed007boss]

I added this here because it needs to stay updated with any new features or fixes. It should be part of the normal contribution flow so that whenever someone adds a new feature, the related info is exposed to modders and included in the docs. That’ll help keep the modding documentation always up to date.

I’m already working on expanding and complete the docs to cover everything, just need reviewers to help keep things consistent and correct any mistake.

Once it’s all in place, I think we should mention this in the contribution guide — so devs remember to update the modding docs whenever they add or change something that affects modders. Keeps everything easy to maintain long-term.

[xezon]

It certainly is nice to have such extensive documentation like that.

If Docs are added to this repository, can it then still be used in the Wiki page? I am not sure how this works, but right now all Wiki pages are in the other Repository (GeneralsWiki).

How many more documents are expected to be added here? And how will these be maintained, given the volume of information they hold?

[ahmed007boss]

I’m not completely sure if we can merge this directly into the Wiki page, but it should be possible since everything there is in Markdown anyway. my plan initially was to publish it through GitHub Pages.

As for the number of documents — my plan is to eventually cover every aspect of the ini files, including all entries like objects, weapons, and configurations such as GameData, AIData, and the different modules. I’ll start with the ones that are used most often and gradually work through the rest until everything is documented.

Right now, the main thing i need to make sure the layout and style of the current documentation feel right. Once that’s settled, I can keep all the new docs consistent and follow the same structure moving forward.

[OmniBlade]

It certainly is nice to have such extensive documentation like that.

If Docs are added to this repository, can it then still be used in the Wiki page? I am not sure how this works, but right now all Wiki pages are in the other Repository (GeneralsWiki).

How many more documents are expected to be added here? And how will these be maintained, given the volume of information they hold?

You'd probably need some kind of CI flow either from this repo to push to the wiki repo or on the wiki repo to pull part of this one. My only concern would be if we wanted to start adding images to the documentation, I'd prefer to limit the amount if binary blobs in the repo, especially if there is a risk of them needing updating as time goes on.

[xezon]

I am inclined to say for now let's push these docs to the GeneralsWiki repo, and if we really need the Docs besides Code, then we move them later from Wiki to Code. This way you can iterate quicker and experiment, because we can just give you Maintain permissions on the GeneralsWiki repo and let you commit whatever in any quantities.

[xezon]

On the other hand, when Wiki is meant to be kept in sync with evolution of Code, then it would be better to be coupled in same Repository. This is true for the whole Wiki. So for example when VC6 is dropped, remove VC6 from wiki.

What is the reason for Wiki to be in a separate repository? Does it need to be separate for GitHub to be able to show it in the Wiki tab?

[Skyaero42]

What is the reason for Wiki to be in a separate repository? Does it need to be separate for GitHub to be able to show it in the Wiki tab?

I can't find in Discord what the original reason was, but it has merit to do documentation in a separate repository for a number of reasons:

• Ownership: Let non-coders have (maintainer) access to the repository without access to the code
• Different workflow: Documentation tends to change more often, even if the code hasn't. Feedback or questions from users leads to re-review or texts in the documentation - and eventually rewrites or extensions. Not to mention spelling mistakes and such. This creates a high volume of small PR's that will pollute commit history.
• Skill: Writing good documentation is a skill by itself. There are developers that don't/can't write documentation, which would defeat the purpose of having docs in the same repository, as the documentation would not be written at the same time by the same person as the code changes. This yields two PR's anyways, defeating the purpose of having docs in the same repository
• Labeling: Writing good documentation is complex and requires good coordination. It is imho better for the wiki to have its own issue and PR list, so it can use its own triage/labeling

In my software business we ran in similar issues, particularly non-coders contributing to documentation, requiring them to send word-documents to developers.

[ahmed007boss]

What is the reason for Wiki to be in a separate repository? Does it need to be separate for GitHub to be able to show it in the Wiki tab?

I can't find in Discord what the original reason was, but it has merit to do documentation in a separate repository for a number of reasons:

• Ownership: Let non-coders have (maintainer) access to the repository without access to the code

• Different workflow: Documentation tends to change more often, even if the code hasn't. Feedback or questions from users leads to re-review or texts in the documentation - and eventually rewrites or extensions. Not to mention spelling mistakes and such. This creates a high volume of small PR's that will pollute commit history.

• Skill: Writing good documentation is a skill by itself. There are developers that don't/can't write documentation, which would defeat the purpose of having docs in the same repository, as the documentation would not be written at the same time by the same person as the code changes. This yields two PR's anyways, defeating the purpose of having docs in the same repository

• Labeling: Writing good documentation is complex and requires good coordination. It is imho better for the wiki to have its own issue and PR list, so it can use its own triage/labeling

In my software business we ran in similar issues, particularly non-coders contributing to documentation, requiring them to send word-documents to developers.

While you make some valid points, I’d have to disagree with a few of them. From my experience working in different development environments, the most effective approach has usually been to keep documentation tied directly to the code. Having the docs in the same repository ensures they stay up to date with every change — developers can be required to update the relevant documentation as part of their pull requests.

The skill gap can be mitigated since most doc updates from developers are small and focused on specific features, and with the help of generative AI tools, maintaining good-quality documentation has become much easier. When combined with a well-known unified structure and layout, generativ AI can produce consistent and professional results even from developers who aren’t experienced writers.

I can actually speak from my own experience here — I’m not a great documentation writer myself, and English isn’t my first language. But if you review the docs I’ve created, you’ll find them well written thanks to clear instructions and multiple AI promt editing cycles that helped me compensate for my weaker writing skills.

I do agree with your point about the higher frequency of documentation updates, but separating repos doesn’t necessarily solve that. In my point of view, intensive and complex documentation auch as this should be handled using specialized tools or platforms, while the documentation in GitHub repos should remain relatively lightweight and closely aligned with the code.

[Skyaero42]

How and where would you publish this documentation?

[ahmed007boss]

How and where would you publish this documentation?

The initial thought was to use GitHub Pages, but since the docs are just Markdown files, they’re quite portable and can be published through pretty much a lot of tool or platform.
They could also be referenced or even included as a sub-repo — for example, under GeneralsWiki — to build a more comprehensive modding documentation and guide.

[ahmed007boss]

On the other hand, when Wiki is meant to be kept in sync with evolution of Code, then it would be better to be coupled in same Repository. This is true for the whole Wiki. So for example when VC6 is dropped, remove VC6 from wiki.

What is the reason for Wiki to be in a separate repository? Does it need to be separate for GitHub to be able to show it in the Wiki tab?

Yes, exactly — that’s the main reason I’m trying to add the docs to this repository. Keeping them here ensures the wiki/Docs stays in sync with the code as it evolves.