search

OutpostUniverse / OPHD

OutpostHD - Open source remake of Sierra On-Line's Outpost
BSD 3-Clause "New" or "Revised" License
110 stars 21 forks source link

Update ReadMe #878

Open DanRStevens opened 3 years ago

DanRStevens commented 3 years ago

I think the main project ReadMe needs some updates.

There are two types of users we need to document for:

The Player guide can list things like hotkeys, and a general gameplay guide. Perhaps bits of lore. We should probably have a section on installation.

The Developer guide should document how to build the game on various systems. Currently we support CI builds for Windows, Linux, and MacOS. We should list the needed tools for each system, and the process to get setup and building. We should also give a bit of detail on how the CI system works, and how people might set that up for their own forked repositories, in case they're shy and want to develop and test stuff in private. We should document how to run any tests, such as the NAS2D unit tests. We should document how to generate API documentation. Currently there is only a Doxygen config file for NAS2D, even though OPHD has some Doxygen style comments.

We might want to move some of that documentation out of the main ReadMe and into separate documents, such as a Player Guide and a Developer Guide. It's probably a good idea to keep the main ReadMe file somewhat short and easy to read through, with links to the documentation sections they might care about. I would prefer keeping the documentation in the repository itself, rather than a separate wiki. I would like to use Markdown for the documentation.

Any other ideas welcome.

DanRStevens commented 3 years ago

Additional notes to add:

Might also want a clang-format format file for code conventions, such as number of spaces between #include and following lines, or before a class, or between functions.

ldicker83 commented 3 years ago

I didn't anticipate the main readme file getting as large as it did. It sort of grew organically as the project developed.

I['m fine with splitting the documentation up since it's getting a bit unwieldy. It can probably also link to the Wiki for further documentation about how to play, etc. Maybe even make the FAQ a Wiki page instead of part of the readme itself.

DanRStevens commented 3 years ago

Was looking at the ReadMe file and thinking we should just drop the Requirements section. The requirements are quite modest so as to not be a real concern. Besides, most games these days don't even bother listing a requirements section anymore. That kind of thing ended years ago, when even low end computers were generally capable of running most things, just maybe a little slower or with lower detail settings.

About the only requirement that's really real is the OpenGL 3.0 & GLSL v1.0. I'm not sure most end users would even know if they meet that requirement. I certainly don't know what OpenGL versions are supported by my hardware. Might even turn some people off from trying. I've seen people assume they can't run games because they only have integrated graphics, but that's actually often sufficient for many games. Might be better to just provide good error messages in game if they somehow don't meet graphics requirements. Let them find out by actually trying.

ldicker83 commented 3 years ago

Graphics requirements... well, I suppose we could lest minimum GPU requirements... e.g., nVidia 670, Radeon 3000 and Intel 3000 or whatever it is. I know on my work machine which has Intel HD 4600 it works perfectly fine and on an old intel graphics netbook I had it ran just fine too. The shaders aren't implemented yet so that requirement can probably just be dropped and even if I end up using the shaders for lighting those can be turned off for GPU's that can't handle it.

DanRStevens commented 3 years ago

Yeah, even that doesn't mean much to me. I don't really know what graphics hardware support my machine has. I suppose it's never been a big enough concern for me to care. I spend most of my time using glorified text editors and web browsers.

If there really are no such requirements, then I'd definitely like to drop the requirements section.

DanRStevens commented 3 years ago

In addition to Linux environment setup for developers, there's also vcpkg setup for Windows developers, which is discussed in Issue #737.