Mirroring Wiki_MiSTer
agg23 opened this issue · comments
What is the relationship between this markdown/the generated site and the wiki (https://github.com/MiSTer-devel/Wiki_MiSTer/wiki)? The development sections at very least seems to be extremely similar, which was confusing to me when trying to learn how certain systems worked.
Would there be interest in keeping these two sets of docs in sync (I assume probably writing from the wiki to here)? Even if it wasn't entirely automatic, it seems like there would be value in automatically creating PRs based on changes.
If this is not desired, what is the desired behavior for adding new information? Are devs adding a feature (or documenting an existing one) expected to edit both repos? How do people know that both sets of docs exist?
The purposes of the MkDocs site primarily was to greatly improve SEO (there is no bot-crawling allowed on GitHub Wiki's) so that people could find the correct information, to have a simpler-to-trace documentation (GitHub wiki's you have to look at each individual wiki page to check the commit history, which is a pain, and it has no git blame functionality), and to be more readable/presentable (Material for MkDocs is very attractive).
There is no way to automatically sync the two currently and it's not something I would want to do anyways, primarily because I rewrote significant chunks of the documentation to make it more readable and flow better for first time users.
I still need to update significant portions of this documentation. I had two deaths in the family very recently as well as a significant mental health issue before that, so I've not been as active on here. I am always open to pull requests being submitted and have merged every single one.
I can just disable the developer documentation since the goal was to inspire people to use this, but it looks like contributors are still choosing to use the wiki instead.
The SEO could be better, but I'm also catching up for years of competing alternatives in search results having years of linkbacks, etc... So it's a slow and steady process:
The GitHub wiki does not have this capability.
Thanks for the response.
I certainly understand your reasoning, and I think that you're definitely right about the non-dev stuff. For dev, I wonder if the convenience of editing a wiki vs submitting PRs is what explains the discrepancy, even if it's ultimately a worse viewing experience.
It seems like for now the solution is to make changes to both, but obviously that will continue producing differences and causing confusion.
If there's any way I can help improve things, I would like to help. I will be submitting at least one PR soon.
While MkDocs looks more attractive to generic user, the Wiki is much easier to find required info, IMHO.
So let them both live together for a while.
Yup, works for me.