more documentation discussion

[wsor4035]

1. is content or documentation needed
2. if 1 then should this repo use the wiki
3. if not 1 then how should documentation be organized
4. should it have examples on how to use submodules
5. should it have a list of mods that use this mod
6. profit?

[SwissalpS]

IMO documentation in repo is an essential part of a good repo.
Extrenal wiki can be an enrichment or tool for collecting info about what should be covered in the docs bound into repo.
So: 1 yes; 2 maybe; 4 yes, depending on importance more in depth or just brief; 5 not much value in that, first focus on 1 and 4.

[S-S-X]

See also issue #4 for earlier discussion and one specific example on how to upgrade scripts to work with submodules (technic integration tests).

[S-S-X]

1. is content or documentation needed

Yes and there's already some. Basic documenation and mod description should fit in readme file while more extensive documentation could go either in wiki or separate markdown file(s).
Links from README.md if documentation is added to wiki or other files in repo.

2. if 1 then should this repo use the wiki

Could use wiki, more important thing is linking from README.md and ContentDB description.

3. if not 1 then how should documentation be organized

Linking in a way that relevant documentation sections are easy to access and find. Basic description like how mod is supposed to be used, how to install mod and basic short list what it provides in README.md.
If extended documentation is added then links from README.md and back.

4. should it have examples on how to use submodules

Basic commands for users who are pulling mods from git repositories.
Basic best practices, options and commands for mod developers who want to use content provided by this mod in their own projects.
Developer documentation should be about this mod and not generic documentation for git, this is mostly covered already.
Possibly mention / link projects that are using different approaches but including too much documentation / attempting to document every possible use case just makes it TLDR and confusing.

5. should it have a list of mods that use this mod

If there's good examples for mod developers and/or other clear benefits then yes, could provide some links but it probably is not useful to list all mods / games that are using this. Just few good and preferably fairly stable examples with clean use cases.