Closed mattclaw closed 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.
I think it's fair to say I misunderstood the purpose. It was shared to me described as being a replacement for the official docs and I came here with that in mind.
I do think you might run into a self-fulfilling prophecy w.r.t. contribution if you don't make the text more accessible and easy to contribute to, but I'll stay in my lane! There's a lot of benefits, I think, to letting people view their content directly in the browser. If you would be interested in it, I could submit an example MkDocs config.
Yes, certainly not a replacement for the official docs and I don't think it should be a part of the official docs.
That said, if you want to take this and set up somewhere that anyone can add to it then I am good with contributing to that instead. My only real requirement is that I'd want a way to print it out as a nice, neat booklet that I can keep with my MiSTer. Having it be available in a book form has always been a goal for me even though I know I could use a tablet or something.
Thanks, I'll close this for now. There are lots of tools out their for generating docs and books!
I'd like to apologize for storming in with a bunch of unsolicited suggestions. Thanks for your thoughtful responses.
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.