☂️ Outdated documentation

[olanti-p]

There's a lot of outdated documentation on the game.

• Some build options no longer work, or require newer versions of software. While mainstream build instructions should be up to date, or at least in a working order thanks to CI, more "exotic" options (for example, BSD builds, cross-builds) may require fixing or doc updates. Possible solution: follow all instructions and update them (or fix builds) if encessary.
• Some screenshots and docs still mention DDA. Possible solution: Ctrl+F, and making new screenshots.
• JSON documentation is frequently outdated. Possible solution: go over data types defined in C++ and examine their loading functions, then compare to JSON docs and update if necessary.
• There is no mechanism that would help maintainer or a contributor determine whether, and how, a change should be documented. Maybe some kind of checklist?
• Documentation is all over the place, with no rhyme or reason and little organization, but that should be solved by docs!: new documentation page #3121

[nsklaus]

there was this idea of an in-game codex as seen here:
CleverRaven/Cataclysm-DDA#36479
( click on that issue's revisions (previous edits) to see mockup screenshots too )
i mention this because it's also a form of documentation.
often time in game, the player is left wondering about the details of objects, places, NPCs and monsters.
typical questions that come to mind are:

• where to find a given object (places it is often spawned in)
• how to obtain a particular object (do i need to disassemble a parent object ?)
• what are its properties ?

and so on.. such details that are usualy scattered in the various UI panels or even worse, forcing users to pause the game and switch to browser to find the needed details. i think it would be good to have it in-game, in a central place. and that would also allow to unclutter the other "examine" panels. as it stand right now, panels try to display too much (unrelated, uneeded) data, like how much damage a backpack would do if wielded.

in-game documentation is currently inexistant or poorly structured (scattered in many panels, in inconsistent manner), forcing user to switch to browser to learn what's what, details on monsters, npcs, and objects to be able to continue to play.

for example:
i want to craft a spear. crafting manager tells me i need "pipe fittings".
what are they ? where do i find them ? do i need to disassemble something to get those ? what properties and other various details do these have ? game message log hints at nothing, and craft manager doesn't know about such "pipe fittings" beside just needing them. idealy craft-manager should allow to select requested component and allow looking at them (requested components) to understand what they are, where or how to get them, etc ...

[olanti-p]

Oh, I guess player-facing content documentation would also count, though it'd be better off in its own issue.

Yes, idea about an in-game wiki, or a codex, or a bestiary, has been floating around for a while.

In DDA there now exists "Lore" tab in the faction info window that collects all snippets player character has encountered in the world:
CleverRaven/Cataclysm-DDA#54499
As well as a "Creatures" tab that can be populated by taking photos of encountered creatures:
CleverRaven/Cataclysm-DDA#56665

There are also 3rd-party tools like Hitchhiker's Guide to the Cataclysm and its BN fork, which do a great job when it comes to summarizing item sources and creature properties, but they're still 3rd party.

Implementing something like that in game may first require ironing out the kinks in the underlying data management (#3142) and UI (#3144) code, and there's a lot of kinks to iron out. It'd ideally have to have actual ingame integration such as item search from crafting menu you've mentioned, so it doesn't end up as just an inferior version of 3rd-party web-based content browser, which means complex UI and attention to QoL and ease of use, which may be difficult to realise with our current UI code.

One of the definite advantages of ingame "wiki" over external tools would be its ability to reflect changes based on what mods are loaded, which would be really useful as many people play with dozens and dozens of 3rd-party mods.

[nsklaus]

thank you for those infos , i'll check it out. i was out of touch with all things cdda related for a while. used to contribute a few things some years ago, like the sprite mirroring left and right trick, the new panel system, and the retroday+ tileset, among other stuffs, but left because i didn't agree with a few things going on around the project. seems to me c:bn is going in the right direction on many points, that's nice to see. i will create a dedicated issue/feature request for the codex.