Xterm.js: Improve documentation

[shalvah]

This is a great tool, as shown by the number of users and companies who trust it. Unfortunately, the documentation is very poor, in my opinion.

Firstly, only a very simple guide is found in the README. What about the other things xterm can do? How do we utilise it effectively?

After lots of searching, I found this, but it isn't linked to in the README. The problem with this documentation is it's written by machines. It lists the classes and methods and properties but doesn't tell you how they work together, how to use them, or what to watch out for. I'm personally struggling with a few issues that I haven't been able to find solutions to.

I'd suggest taking out time to write more friendly guides, explaining how you would use xterm in typical scenarios. I understand that this is OSS, and everyone working on it probably has other daily responsibilities, but maybe we can put it on a to-do list somewhere. I'd contribute to the docs, but I haven't been able to get xterm to work, so I'm still lost.

_PS: The README section on "Addons" is misleading. It omitted the fact that you might need to add its CSS for an addon to work._

[Tyriar]

Thanks for the feedback! You're right that everyone else has things to do, I think we're waiting for a documentation champion to come along and improve this situation. Here's a list of TODOs in the meantime:

• [ ] Improve getting started guide, explore some of the things you can do with xterm.js
• [ ] Add code examples to the .d.ts (which will propogate to the website) https://github.com/xtermjs/xterm.js/issues/1476
• [ ] Mention addon CSS files in README https://github.com/xtermjs/xterm.js/pull/1556
• [ ] Mention the source of truth for the API currently is the .d.ts in README https://github.com/xtermjs/xterm.js/pull/1556

[shalvah]

No problem @Tyriar . Hopefully, I can get xterm working and contribute to the documentation when I ~have~ make some free time.

[jtviolet]

@shalvah I have been using xterm.js for the last year now and I have been looking to start contributing in a meaningful way. I am going to work on a revision of the documentation this weekend and submit a pull request. In the meantime, feel free to reach out to me and I can help you with your xterm project as best as I can.

[shalvah]

That's nice @jtviolet. I was finally able to figure things out. I guess my biggest challenge with xterm.js came from thinking it provided expected terminal functionality, like handling/displaying input. Didn't realise it was so barebones and you had to implement lots of stuff yourself. But I making progress now.

[cubiclesoft]

xterm.js definitely needs better documentation (especially the Terminal.on() event listeners).

[Tyriar]

Most of this is done, please create more focused issues if we're still lacking.