Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Talkin' 'bout documentation #133

Open
SquidDev opened this Issue Mar 1, 2019 · 11 comments

Comments

Projects
None yet
7 participants
@SquidDev
Copy link
Member

SquidDev commented Mar 1, 2019

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?

@SquidDev

This comment has been minimized.

Copy link
Member Author

SquidDev commented Mar 1, 2019

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

@osmarks

This comment has been minimized.

Copy link
Contributor

osmarks commented Mar 1, 2019

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.

@hugeblank

This comment has been minimized.

Copy link
Contributor

hugeblank commented Mar 1, 2019

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.

@vpontin

This comment was marked as resolved.

Copy link

vpontin commented Mar 3, 2019

What about using this very repo's wiki feature?

@Lemmmy

This comment was marked as resolved.

Copy link
Contributor

Lemmmy commented Mar 3, 2019

@vpontin - read the issue:

@BombBloke

This comment has been minimized.

Copy link
Contributor

BombBloke commented Mar 9, 2019

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.

@Wilma456

This comment has been minimized.

Copy link
Contributor

Wilma456 commented Mar 13, 2019

@vpontin

This comment has been minimized.

Copy link

vpontin commented Mar 13, 2019

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

@SquidDev

This comment has been minimized.

Copy link
Member Author

SquidDev commented Mar 13, 2019

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 :)).

@vpontin

This comment has been minimized.

Copy link

vpontin commented Mar 13, 2019

Pingging @Vazkii if he want to clarify some points

@SquidDev

This comment has been minimized.

Copy link
Member Author

SquidDev commented Mar 17, 2019

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.