Update

I'm hosting some proof-of-concept documentation. Please give any comments you have on the accessibility, usefulness, etc... of the docs.

This is my documentation, this is my documentation baby.

Because this can't possibly end badly.

The problem

CC:Tweaked's documentation is a bit of a mess right now. There's effectively three "sources" of documentation, none of them perfect.

• CraftOS's help files: Ideally this would be the "canonical" source of documentation. However, I have failed to keep this updated as the rest of the mod has changed (see, for instance, changelog) and so it is woefully outdated.

  Moreover, the documentation itself is pretty flawed. It's very hard to have something readable given CC's small resolution, but the large monochromatic walls of text don't help. While documentation for programs is generally pretty good, documentation for APIs often ends up being little more than a list of functions provided, which isn't very helpful.

• GitHub wiki: This was added to document the changes to the original mod, which is fine, but again makes it very hard to consume as you have to refer to two sources.

• cc.cc wiki: This is definitely the best documentation we have right now. However, I personally find it hard to keep it up-to-date (despite the fantastic templates, adding new functions takes much longer than I'm comfortable with), which means some features are still not documented.

The ideal

As far as I see it, there are three-to-four separate things to document:

• API/library reference: A list of all functions, a summary of what they do and documentation on parameter/return values. Effectively the same sort of stuff you see for any library.

• Program reference: List of all programs, what they do and what options/arguments they accept. Should probably also include some example usages - think man pages.

• Guides and tutorials: I'm not sure if this counts as one or two things. But effectively more long-form write ups of one bit of the mod. This would probably include documentation on the blocks/items themselves, but also more general topics like "terminal redirects", "using the turtle API", etc...

In my opinion, the first two would be best served as being part of CC:Tweaked/CraftOS itself, while tutorials and long-form stuff should be driven by the community. Having reference documentation closer to the code should make it easier to ensure the documentation is in sync*

* Obviously this hasn't been the case so far - I'm definitely going to start requiring documentation updates as part of changes I or other people do.

The proposal

There's a couple of changes I'd like to make:

• Improve the builtin help program: This has been something I've wanted for a while (see dan200/ComputerCraft#212) - at a bare minimum, help should be able to do some colouring of sections and pagination.

  As a more long-term thing, I'd really like to see something closer to Emacs or Vim's help system - pages are linked together and you can navigate between and within sections.

• Investigate LDoc for APIs: Effectively, aim to bring the function documentation into the module itself. This should allow us to be more comprehensive than the existing help files, and (hopefully) ensure the docs are kept more up-to-date.

  One'd need to think about how this plays with help. I'm rather envisioning generating help files for each function, and then the API file includes the module description + a list of each function and links to them.

  I'm also not quite sure how this will play with functions not bound directly to Lua APIs - such as window objects (rather than the window API) and all Java-side code.

  One nice thing though is we could also generate HTML documentation (and then host it online) which generally makes easier to consume.

To discuss

Obviously I'd like discussion on all of the above points. I may just be talking about a problem which doesn't exist, or trying to introduce complexity for the sake of complexity. There's a couple of obvious problems I see with the above though:

• How does this impact contributions: One nice thing about the wiki is that it's much easier to contribute. You don't need to sit down with Git and create a PR - there's a much lower commitment level required to make a change.

  I'd still like the wiki to be a thing - the proposals only really impact the official "reference docs" for CraftOS - but it does hamper anyone's ability to contribute to that.

• How does this impact beginners: I want CC:T to be just as, if not more, accessible than ComputerCraft. Do any of these changes (especially to the help program) make it harder for new people to find or consume help?

First! Also, wow - that's one massive wall of text.

Anyway, I'm creating this issue as I believe the current state of documentation is unmaintainable. While I'm obviously soliciting feedback on my proposed changes, if anyone has ideas on how to make the mod more accessible, better documented, etc... then here is the place to post them!

It might also be worth getting ideas from the wider modded community - i.e. people who aren't using the mod incredibly often, but still enough that they have qualms with it.

I don't really like ingame docs much. As you said, the tiny ingame screens just aren't that good, though having documentation ingame and on the internet generated from one source is reasonable. The help program could, though, be made to pull from the wiki somehow, which may be better.

I think that @osmarks idea should be done in the opposite direction, where documentation/comments from within the game/source code is parsed and put on some sort of webpage, in addition to having a help program parse it in-game. I wouldn't necessarily call the aforementioned webpage a wiki, since it wouldn't have any sort of demonstrations of the program.

What about using this very repo's wiki feature?

@vpontin - read the issue:

I feel that the vast majority of users will avoid CC-screen-based help and look for online documentation instead. Tabbing out to a wiki is significantly easier than, say, building another computer so that you can have your character switch to a different screen without closing down the edit script and argh I have to spend more gold on more advanced computers just for documentation....

Sure multishell is an option on some systems, but it's the sort of option we can assume new users aren't going to be aware of (unless we start mentioning it in the system boot message or something?). Likewise, a colourful help script with a GUI and clickable pages links etc isn't much good for beginners plonking down computers made out of stone.

So frankly I don't think there's much point in having any "on computer" function documentation at all. If users have a choice, they'll tend not to use it. If it's the only choice, they'll tend not to use the mod. RIP OpenPeripherals.

Of course, in-game help doesn't have to be provided via a CC screen - the hallmark of any retro system is a paper manual thick enough to've killed a whole tree. Provide a book item with a decent interface (ToC, index, search functionality, place saving), links to online resources (a good excuse to leave the stuff in the book very brief), and you're all set. This'd provide a more natural way to provide in-game block / item documentation, too.

What about this ingame help viewer -> http://www.computercraft.info/forums2/index.php?/topic/27898-ghv-glorified-help-viewer/ ?

Or if Squid really wants an "external" help system for using CC:T, maybe using Patchouli would be a way to go

https://minecraft.curseforge.com/projects/patchouli
https://github.com/Vazkii/Patchouli/wiki

Patchouli would definitely be worth investigating. I'm always a little worried about adding external (albeit soft) dependencies, but at the same time it saves on work from my end.

One thing I feel would be worthwhile is allowing opening "the manual" from the CC GUI (though not the computer itself). It could potentially be faster than any online docs if you only need to look up a few functions. Similarly, you could do some nice dynamic stuff with also showing the APIs for connected peripherals, turtle API if you're a turtle, etc...

However, this would be pretty complex to get working in a way which feels polished (and accessible to beginners), so definitely worth exploring more before even looking into an implementation (and would probably need to get some actual docs first :)).

Pingging @Vazkii if he want to clarify some points

OK, so I put together a bit of a POC and documented a few modules.

I've put the results online, and would really appreciate people's thoughts on the concept. I'm aware the content is a little lacking (it was largely copy and pasted from the wiki), and it not the prettiest thing in the world.

Some thoughts of my own:

• Not having decent examples/usages is a bit annoying - they're limited to one line, and you can't add explanations of what they're doing. Obviously one doesn't want massive blocks of code in your comments, but it might be worth modifying LDoc to allow something extra.
• Having to document every argument and return value can be a little frustrating at times - sometimes you want to combine them and say "these three values do X".

On the flip side, it was incredibly easy to put the actual docs together (though I was just able to copy from the wiki). Maintainer wise, it's definitely what I'm looking for, I guess the question is if they work as docs.

What about the APIs that are made in Java? How are we going to handle those?

@hugeblank Stub files

@Lemmmy Fair enough.

The POC is in my opinion what the documentation should be. It's clear, functions can be found pretty easily and everything is always in reach with 2 clicks. On the CC wiki it took me personally quite a few clicks to find something I needed.

I do think that some text guides should be made. but I can imagine that it can be wise to put those not in the documentation itself. A link to it should be there of course.
For those guides we might be able to use the github wiki as a starting place.

I do get your point on the "having to document every argument". It does feel tedious sometimes.

The pros of having the documentation in code is that API changes are immediately shown in the documentation as well. The con is that expanding the documentation might take a bit more effort for people who are not used to git compared to a regular wiki.

Just leaving this as info, what i do for my mods is having the Wiki on Github as it can be synced easy with a simple git pull task in the build process.

All you need for ingame manual is either some Addon that can read markdown or your own manual item.

(RTFM from Vexatos for example is able to read the markdown)

I'm glad that you're talking about this general topic. I'd be classified as a CC beginner and a fan of good documentation. I may also be willing to contribute. One issue that I've consistently run into on the wiki (and maybe elsewhere) is a clear and effective way to sign up as a contributor to the wiki or a participant in the forums/talk pages. I would suggest that you/we help resolve this issue so newbies like me don't feel discouraged. :-)

The POC looks really nice and it's easy to get information out of. If the documentation would be as well-maintained as the Urn documentation, this would be my strong preference. Generated documentation is in my experience easier to QA and maintain.

I would remove the GitHub wiki in favour of a home page (whether that be the home page of that POC site, curseforge, the README) that explains all the changes in short.

Great POC! Could that kind of doc be generated directly from code’s documentation as @StefanJanssen95 was saying? Don’t know if that’s the best solution but it would surely be easier to maintain and keep up to date.

@GilDev Thanks!

That's pretty much what's going on already - see the feature/doc-gen branch for the documented code. I'm hoping to get this all merged into master soonish™, just trying to finish off the documentation tooling first.

Alright, that’s great!
And thanks for your implication in CC:Tweaked, it was awesome to be able to play with ComputerCraft with the latest Minecraft version the same way I did 5 or 6 years ago. Brought back quite a few memories! I truly think this mod made me even more want to become a developer when I was a teenager.

I'm totally with BombBloke on wanting web documentation. One additional point is that when I see a mod and they don't have online recipes, descriptions of what's in the mod etc I tend not to even try it out--I want to know what I'm getting before starting up Minecraft. I think APIs are good too in CC's case--browsing the wiki totally sold me.

That said I also know some mods where they want you to open up Google mid-game to progress and it drives me nuts, I'd find (good) in-game documentation relaxing and not a total waste of time. I'm not sure if "good in game documentation" and "help on a CC screen" really sound simillar, though... it would probably be a bigger change.

Let me know if you'd want any help with writing and/or autogenerating.

Over 18 months later, I think I'm going to close this issue. tweaked.cc is at the point where I'm pretty happy with it.

The current system is by no means a perfect solution, and still incomplete in many different ways. I'm planning to create some issues over the next few days which describe some more concrete tasks we need doing.

As always, if people do have thoughts/suggestions, please do leave a comment or create a new issue.

Congrats on your work and those that have contributed!