Documentation: wiki vs .mds

[kmhuff]

Hi, I'm new to the project. @gfgtdf and @Pentarctagon helped me out with a compiling issue yesterday here.

I've noticed that there tend to be a lot of duplicate topics between the wiki documentation and the .md files here on github. It seems to me that this makes it easy for one or the other to get out of date, and might result in newbies like me missing important information.

Examples:

• There's a lot of good info on formatting in CONTRIBUTING.md that might be useful on the Coding Standards wiki page.
• The Compiling Wesnoth on Windows wiki page was recently updated, but the .md files in projectfiles remain the same.
• There is information in Compiling Wesnoth that hasn't seemed to have made its way into INSTALL.md.

My proposal is to add any information in the .mds not already in the wiki, then change the .mds to point to the correct wiki page or pages (or vice versa). This will make keeping documentation up to date less painful and reduce the chance of someone following outdated instructions.

I'd be happy to make this change myself if the community agrees that it's a good idea.

[github-actions[bot]]

Hi! Thanks for helping make Wesnoth even better!

[Pentarctagon]

I've updated the INSTALL and other readme files to have the correct compiling information. The wiki pages have therefore been removed so as to prevent anyone from accidentally still using them.

[Pentarctagon]

@kmhuff Also, if you want to move over the information from CONTRIBUTING.md, that's good too. FYI though about how you'll need to get a wiki account created though: https://forums.wesnoth.org/viewtopic.php?f=17&t=43815

[Vultraz]

I'd rather we move information to CONTRIBUTING.md, rather than out of.

[kmhuff]

When I get a wiki account, I'll add any relevant info from the wiki to CONTRIBUTING.md and add links from the wiki to the file. Does that work? In general, do we prefer having info in the files here on github?

[Pentarctagon]

I'd say that here makes, since this is where people submit the actual issues/PRs/etc.

[soliton-]

In general, do we prefer having info in the files here on github?

I would say that any info that directly pertains to the code in the repo should also be in the repo. So the README and INSTALL files should by up-to-date and authoritative. The CONTRIBUTING file is good to contain some general hints and pointers to other places. Not sure we'll be able to fit everything in there.

The wiki is good for more extensive info and stuff that we won't be able to maintain like how best to install dependencies in your favorite linux distribution or so.

[rubyFeedback]

Personally I prefer .md files these days, but mostly because I like to document/comment my own code. On the issue here, I am not part of the wesnoth team, just a simple player; I don't mind as much the format, as long as the documentation is of high quality. (One thing that could be improved one day may be the in-game help, in particular adding search functionality; right now searching via google is so much more efficient and I don't think this should be the case, but I digress.)

It's ok to split up the main README into separate subsections. I have to admit that I rarely go to the wiki; I assume many others will also first look at the README and go from there, with only a few going to the wiki specifically.