EmuHawk needs a user manual

[YoshiRulz]

What should go in the manual?

Everything that doesn't belong in the wiki. Yay tautology! My notes are a little more detailed on what I consider a technical reference (for user-developers or for ourselves) vs. a manual (for end-users). I also envision a separate user manual for DiscoHawk, and maybe one for TAStudio. In many cases, our interface could be simpler, or even include documentation "on the page" as it were. But doing that also takes effort, and it still wouldn't completely remove the need for a manual. Oh and re: TASVideos, it makes sense for the site to have tutorials for how to do TASer stuff (recording and TAStudio, RAM search, Lua scripting) with EmuHawk since it has similar pages for other emulators. It also makes sense to keep a few other pages there. But I believe all BizHawk documentation should be solely or also in this repo—checked-in if it describes how software works, otherwise in the wiki or issues.

What file format should it be in?

The manual could either be "source-only" (which leaves HTML and maybe Markdown), or it could be compiled into multiple formats from source files in some domain-specific language (preferably one based on Markdown). The only technical constraints are that it's offline/client-side and that it runs everywhere EmuHawk does. Plus Android and macOS because those don't seem too far away. (I'd like man and info outputs but that's not a requirement.) It should also have a FOSS editor / LSP server, and, if applicable, a FOSS compiler. We should be thinking about localisation from the start. While none of the text (and after UI is localised, none of the screenshots) can be shared, the source files can be structured such that it's easy to tell how much a localised copy is missing compared to the base, and that it's relatively easy to create a new localisation.

Some candidates:

• .chm (Microsoft Compiled HTML Help—also readable on Linux, not sure about Android or macOS)
• mdBook
  • write in Markdown, outputs HTML
  • used by: Nix, Rust ecosystem
• Material for MkDocs (fork of MkDocs)
  • write in Markdown, outputs HTML
  • used by Elasticsearch and a bunch of SV corps apparently
• Sphinx
  • write in reStructuredText, outputs HTML
  • used by: MAME, Python ecosystem
• Antora
  • write in AsciiDoc, outputs HTML
• TiddlyWiki (single-file webpage incl. the whole wiki system)
  • write in WikiText (bespoke, not MediaWiki's), outputs HTML
• IDK look at these

How should pages be laid out?

Like this (draft only) or this (ditto). We can go back to the roots of hypermedia/hypertext and have small, highly-linked pages. Or we could have a mix of small pages for tutorials and medium pages for breakdowns of each feature/tool. We can disregard print layouts—you need a multitasking OS to use EmuHawk anyway—the eschewal of long pages is only to reduce cognitive load. Links to pages and to headers, inline images, and tables are all going to be necessities when choosing a format. I've started collecting screenshots here.

How should the writing process go?

There's little point writing hundreds of wiki pages just to go back and rewrite them all in a different markup language, so it seems obvious that choosing the tech should be the first step. That said, I'm thinking we can work on the formatting/style simultaneously by having just a few pages that we continuously re-draft. It doesn't matter what their subjects are so long as everything is used at least once between them—they can include links to nonexistent pages. For inspiration, there's some docs in the readme which I'm keen to get rid of, and a bunch of outdated stuff on TASVideos.

[vadosnaprimer]

I suggest https://en.wikipedia.org/wiki/ReStructuredText for format. Can be shipped as a PDF. Example https://docs.mamedev.org/

For the structure, just do it like fceux does it and go through all menus and dialogs. https://fceux.com/web/help/fceux.html