adreeve
commented
3 years ago Thanks for the thoughtful and well articulated comments.
First off, I am well aware of the purpose of github as a source control repository. Someone suggested putting this here so it had a URL outside of Facebook so I did.
Unfortunately, I think you misunderstand my goal here. My goal is to focus more on how to use a particular system once it's up and running than MiSTer oriented specifics. If anything, I'd want to take it in the direction of also providing info pertinent to MAME users... etc. I view it as a bridge between knowing nothing about a system and wanting to actually go read the manual (which is why I've decided to start trying to provide links to manuals for those that want to further). There is MiSTer specific instruction in here such as keyboard equivalents and references to the OSD because of exactly what you say... I don't want someone to have to go back to the MiSTer Wiki to look everything up. At the same time I am generally trying to leave out setup info with respect to ROM BIOS images and getting a core up and running with the occasional exception. I'm not necessarily terribly consistent, though, because the main goal of this is to be a reference for me and if others see it as helpful then great and if not then no problem. I also suspect the goal of the MiSTer wiki is not to teach people how to use each computer, but rather how to get each core working.
I have thought about moving to markdown, but unless I see some efforts to collaborate requiring regular merges then I don't see much reason to do so. So far I have had exactly one person send me an updated document that I had to merge and that was to add bookmarks to the index. If I see a surge in outside desire to contribute helpful system specific instruction then I'd be more likely to spend time doing that.
mattclaw
I think contributing to the MiSTer ecosystem is a great goal and the work you're doing here is valuable! However, I have a few thoughts on this repository:
When creating documentation, checking in PDF and DOCX files to a git repro is a bit of an anti-pattern and breaks many of git's features:
Furthermore, neither format is ideal for reading with plaintext editors, so they're a bit less accessible and far more inconvenient.
Ideally, this documentation could be stored in a plain text format, such as markdown, and then rendered out to whatever formats folks prefer, and served via Github's "Releases" feature (or published as HTML to a static website). This would allow a single source of truth to exist, and for changes to be easily propagated out to the various file formats.
I think most importantly, this repo represents a duplication of effort. It's my opinion that it would be more effective to contribute to the official documentation for reasons of visibility: how would new MiSTer owners even know about this repo? Creating a new and separate source of documentation further muddles the water and doesn't address the root issue - the official docs will still be outdated even if this documentation is more current. Please consider porting your documentation back to the official Wiki and Core repositories where, I believe, it would be more impactful.