The PICO-8 manual as it stands today is flawed. What I mean by that is not only is it organized in such a way that makes it harder to gleam certain information out of it, but it also has flaws and inconsistencies with what the PICO-8 actually is. It also omits important information, such as cycle count and the extra 16 colors. eevee has already taken note of some of these flaws, but I still believe there may be more out there. There's the PICO-8 wiki, but that's not fully documented either. What we need is a new way of organizing known information about the PICO-8 into a manner which makes sense and is simple to use.
I propose the creation of a PICO-8 technical manual, a manual that fully documents everything the community knows about the PICO-8, both it's version of lua and it's editors, as well as the programs on it. It will be a collaborative project. Alternatively, we could fix the current PICO-8 wiki in such a way that it accounts for these flaws, is more detailed and easier to use. Both of these options I think could really help people like me who wish to delve deeper into how it works exactly.
Cycle counts could be there in an appendix, but I disagree about secrets. It’s part of the game to find them, and the info is already super present in the wikia wiki or on discord.
(Also quite rude to come here and say things suck.)
I have indeed seen the advanced manual before, and have used it for one project of mine. However, I still don't think it's ideal, since it's pretty unorganized.
As for merwok, personally, I don't like the idea of "secrets" when it comes to the PICO-8, since I see it more like software development than a "game". As such, I think the documentation should be made as clear as possible. Sorry for saying it sucks by the way, I didn't mean to be harsh.
The wiki already has an article on CPU timings. Feel free to improve it, or use the commenting interface to make suggestions. https://pico-8.fandom.com/wiki/CPU
I'm confident that you'll have better chances of success just extending the wiki than starting over. Its founding purpose was to give the community a low cost way to extend existing nodes and branch off new ones to capture new information. You're right to notice that keeping that information organized—let alone useful for novice programmers—is a ton of work, but it won't be less work starting over.
That said, I'd also rush to agree that Fandom Wiki is a challenging environment for structured technical documentation. A Jekyll project in Github Pages, or a Sphinx project in a repo with a CI build-and-publish step, could be a compelling way to collaborate on a new book-like project. I think it's fair to say that it'll only work if a single person or small group makes a large seed investment in a first draft. The Fandom wiki started with someone creating an empty account and telling everyone else to write it, and nobody did for many months. I seeded the first 150 articles with about two weeks of full-time effort when I was stressed out at work and needed something else to take my mind off of it. :)
Maybe we just need to do a pass over existing wiki articles to put together a more comprehensive hierarchical table of contents. Suggestions welcome.
@StinkerB06 Ooh, I like those websites you've provided! If this manual actually existed, it should probably be structured like one of those.
As for @dddaaannn, I think a wiki would indeed work well enough, but as you said, Fandom wasn't really made with technical documentation in mind. I was thinking we could use Miraheze instead, though I'm not sure that would exactly work either. It would look better, at least. (Also, thank you for helping grow the wiki!)
I guess I was thinking MediaWiki in general isn't good for structured technical documentation, especially the "structured" part. Implementing tech writing constructions and organizing hundreds of topics requires file-like access to sources to do well. (My recently added P8SCII article makes heavy use of tables that I used custom scripting to produce.) The GBDev PanDocs that Stinker806 mentioned uses mdBook, though it looks like they did a one-time conversion from a MediaWiki to start it, so that's interesting. Github now makes it about as easy as a wiki to contribute changes to a repo directly from a browser.
It sounds like the main concerns are perceived completeness and findability of information in the wiki. The example topics you mention are already represented: cycle count, extra colors, Lua features. (We could add brief examples of ipairs(), next(), select() to the Lua page to complete eevee's list.) That's why I think improvements to the table of contents to make it easier to see at a glance what topics are covered would address the concerns.
If it still seems like an all-new project is warranted, maybe you could write up a sample outline to start. Even if those topics are already covered in the wiki, a cross-reference from the perspective you're describing could be useful.
[Please log in to post a comment]
