Have a wiki for the items

[TotoShampoin]

Useful information to include:

• Basically the same as Minecraft Wiki, but for the items in CCT, much like the original one
• It'd provide recipes (even knowing there's the crafting book)
• It'd also provide useful informations about the computers, turtles and all that are otherwise unknown and unintuitive.
  • For example, the fact that turtles aren't compatible with non diamond materials (by default),
  • or that turtles can be used in a disk drive. Two things that were told to me, and not found out anywhere on the internet.

[Wojbie]

Related: #1677

[SquidDev]

One of the tricky things about docs is trying to find how to structure them so information is easily findable, but not also not duplicated in too many places. We've definitely not got that right yet.

I'm not sure if item-based pages are a help or a hindrance here. On one hand, it's a useful place to document behaviour that doesn't belong to an API (such as dying turtles), but on the other hand it does mean information is more spread out across pages (do I look in the 'turtle API' or the 'turtle item' page).

It is going to be tricky to avoid having such pages just be a list of things. But I guess maybe that's fine — most of the rest of the docs is "Reference" documentation, so I guess it makes sense for item pages to be too.

---

I think #1677 is trying to solve a different problem — that's more around tutorials/guides.

[tonitch]

I recently found out that simple "dump" page of information is often enought to satisfy this need : https://github.com/Tiviacz1337/Travelers-Backpack/wiki for instance I can get pretty much all the info I need about the mod (craft, item's usage, ...) my guess is that it would fit in the "reference" section of the tweaked.cc page. For instance a "crafting" section and a "particularity" section would answer most questions. I actually had trouble finding craft too and this was the first section I checked.

[RrkwM]

Maybe you could add unorganized information in the Github Wiki first. Just explain to players the items, forget about perfectness. It's rather more upsetting to know absolutely nothing about them.

[SquidDev]

I'm not sure if item-based pages are a help or a hindrance here

To be clear, this was a genuine "I don't know" (I know sometimes this reads as a "it's a bad idea, but let's present both sides"). What I'm mostly trying to acknowledge here is that writing documentation is a lot of work — I don't want to dive into writing more things, if half of it ends up being useless!

I think probably a better thing to do now is if we build a list of what things aren't documented and/or are confusing to find right now, and then work out how to organise this later. Off the top of my head, I can think of:

General

• Pocket computer, turtle, and disk dying and undying.
• Computers (and turtles and pocket computers) in disk drives. This is mentioned on the drive page, but perhaps it should be elsewhere too.
• Overriding capacity of computers/floppies.
• All the config options.

Computers

• Computer recipes.

Disk drives

Honestly, the docs here are shockingly bad. There really should be more information about the motivation for them.

• Disk recipes.
• Disk drives playing Minecraft record disks.

Pocket computers

Again, docs here are incredibly perfunctory.

• Pocket upgrades.

Turtles

• Turtle tool specifics: for instance, mentioning limitations/features of the various tools, like tilling soil with a hoe, and how axes are entirely useless!
• Turtle dying.
• Turtle overlays. I kinda like that this is a bit of an easter egg, but probably should document it.
• Dinnerbone turtles. This definitely is an easter egg, and probably shouldn't be documented, but mentioning for completeness sake.
• All the turtle datapack features (as Wojbie mentions, see also More long-form documentation #1677).

Printers

Again, this whole page is very bare-bones.

• Some explanation of how to use this. More long-form documentation #1677 mentions it would be neat to have a full tutorial about the printer, but we really need a basic "here are the slots, here's what you use for ink".
• Placing printouts in item frames and lecterns.

[TotoShampoin]

Related: #1677
@Wojbie

Wh- But- But you're the one who told me I should post an issue here ;-;

Maybe you could add unorganized information in the Github Wiki first. Just explain to players the items, forget about perfectness. It's rather more upsetting to know absolutely nothing about them.
@RrkwM

100% with you on this one, unorganized documentation is better than no documentation (Ctrl+F comes in handy in this case)

...
@SquidDev

I guess that would be a good start. Maybe have a thread or a form of some sort somewhere, were anytime we search and don't find an information in the wiki (even with that search bar), we add to the list?

[SquidDev]

Wh- But- But you're the one who told me I should post an issue here ;-;

I think this was more of a "see also", rather than a "this is a duplicate".

Maybe have a thread or a form of some sort somewhere

Oh, I was just planning to co-opt this issue for that, but also happy if people just want to file a new issue.

[vico93]

I agree - with an wiki like MC wiki we could integrate it with HeyWiki too

[ajh123]

I agree - with an wiki like MC wiki we could integrate it with HeyWiki too

That would be easy to do since it requires adding files to a resource pack, CC-Tweaked already has a resource pack so the files can be added to that one.

HeyWiki also supports wikis not made with MediaWiki (the software that the Minecraft Wiki and Wikipedia uses) so the existing https://tweaked.cc site can be used without too much work.

[chuman72486]

Not sure if this is still an issue to be discussed, but I agree that there's a lot of information lacking in the current documentation. Some APIs and functions are fairly well documented, with functional examples and use cases so I can understand how each function works... but then others are just "here's a function, it exists and does a thing" and not much more than that.

In most cases, each API is relevant to a specific item or type of item, like monitor is only for the Monitor and Advanced Monitor peripherals. In these cases, the API page should have a section referring to a list of relevant blocks that implement that API, with links to wiki pages for each item (complete with crafting recipes, variants, upgrades, etc)
Similarly, wiki pages for each item should have a section showing the APIs implemented, with links to each API.

Example:
I search for "Advanced Turtle", I get a generalized Turtle item page.
On the item page, I get a basic description of what a Turtle is and the two variants, Turtle and Advanced Turtle, with their crafting recipes.
In the next section, it goes into detail on what a turtle can do (assuming no upgrades). This section does not specifically mention the APIs, only what it's able to do (move around, interact with blocks/mine blocks, pick up and carry items, as well as run all the same computer programs a regular Computer can)
Next section is about the specific upgrades, with links to relevant pages for the accessories like modems, speakers, etc, as well as what tools can be equipped and what abilities the turtle gains with each peripheral or tool.
On a right sidebar will be a specs table, which lists technical details like the types of Turtles, implemented APIs (with links), screen size and color capabilities, compatible peripherals, acceptable fuels and fuel capacity, and other specs relevant to Computer-like blocks.
There would also be an additional sidebar below the specs with "related items", referring to similar things like the Turtle API, Computer item, Modem item, etc.

All item pages would follow a similar design layout so people can quickly know where on the page to look for the information they need.

API pages would have a similar design, with a specs sidebar showing what items implement the API, relevant specs for the API like range limitations on modems, item push limits for inventories, events associated with the API, etc.
Specific functions should show more than just a simple description and syntax. There should be a functional example of how the function could be used, what it should return (table structure with expected fields, etc) and limitations of the function, if there are any.

Events should have their own pages, with better documentation on what to expect when specific events are received. What's the table structure look like? What kinds of things can cause the event to trigger? How often can the event trigger (every tick? only the first time a thing happens? every time a thing happens?)

Other data structures should be documented as well, especially if they appear across multiple APIs or functions. Things like an item's data structure (the table containing name, amount, NBT, display name if available, etc)

The important thing is to make every possible bit of information available. Don't neglect being able to have multiple pages with links back and forth. No matter what page you land on, if it doesn't have the information you were looking for, there's probably an easy to find link to where the information can be found.

[Wojbie]

Hmm. Events do have their own pages with structure explained https://tweaked.cc/event/peripheral.html . Tho I agree having a bit more detail about some of events would be helpful.

Some structures like file handles and websocket handles are documented, but basic ones like table with item data indeed is only shown as example, which does seem like something to improve. Detailed item table is definitely not documented.