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.
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]