search

MJoergen / C64MEGA65

Commodore 64 core for the MEGA65 based on the MiSTer FPGA C64 core
GNU General Public License v3.0
26 stars 4 forks source link

Next level documentation #147

Open sy2002 opened 1 month ago

sy2002 commented 1 month ago

@MJoergen @paich64 @Kugelblitz360 FYI

The C64 core is large enough and powerful enough that a lot of use cases can be covered. Emulated use cases. Use cases with different hardware setups. Modern C64 "stuff" such as Midi and mssiah. Or EF3 and stuff. Or SD2IEC and C64 OS. And retro cases such as using years old CRTs with the right 15kHz CSYnc. GEOS with RTC. Games with paddles. Modern USB Mice with appropriate adaptors. Demos that need the C64C's CIA. Multi-SID setups. And so on and so on.

Currently, we try to solve that by having the main user's manual README.md and the Frequently Asked Questions FAQ.md that then has links to various other *.md documents in the /doc folder of this repo. The user experience sucks and therefore a lot of people are not even reading this. Even the ones who are willing to read have difficulties due to the size of the documents, the fragmentation of the information and the sheer hurdle that people are not used to read docs inside GitHub. Also GitHub's Wiki only brings you so far...

MiSTer on the other hand leverages a tool that I do not know, yet. It is called MkDocs: https://www.mkdocs.org/

This thing leverages GitHub and GitHub .md files and outputs a nice documentation website: https://mister-devel.github.io/MkDocs_MiSTer/

With menus and chapters like a book. Images, diagrams, search function, ...

I am not saying we should use MkDocs. What I am saying is: We need to think about a next level documentation for the C64 core, that solves for the above-mentioned challenges, also given, that we are in the meantime (or at least soon) talking about thousands (plural) of users of the core.

What appeals to me at MkDocs is the coder-friendlyness of the documentation's sources. As seen here: https://github.com/MiSTer-devel/MkDocs_MiSTer/

That means for me that even if someone else would take over the documentation from me (highly appreciated), I could still quickly add/edit the documentation after I coded something in VHDL or Assembly and the core changes: I quickly edit an MD file instead of having "to call the documentation guy". Plus: Versioning and GitHub comes for free.

Kugelblitz360 commented 1 month ago

As I have some spare time from now to August 10th I volunteer in writing clear Q&A and core documentation so others can work on code instead :-) Most likely, starting September, I have a day-job again, but working on formats and foundations in the next weeks is no issues. I will talk to @sy2002 Monday anyway.

sy2002 commented 1 month ago

I assigned this one to @Kugelblitz360 as he owns this issue. We will close it when the first version of the new documentation is available. The current setup is:

  1. We use a GitHub repo in Kugelblitz' own GitHub account: https://github.com/Kugelblitz360
  2. As soon as the MKDocs based website stands, we will remove documentation from here and instead LINK to the real thing
  3. Maybe we can get a c64.mega65.org subdomain that links to the documentation