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

Documentation updates #785

Closed
ark120202 opened this issue Dec 31, 2019 · 1 comment · Fixed by TypeScriptToLua/TypeScriptToLua.github.io#6
Closed

Documentation updates #785

ark120202 opened this issue Dec 31, 2019 · 1 comment · Fixed by TypeScriptToLua/TypeScriptToLua.github.io#6
Labels

Comments

@ark120202
Copy link
Contributor

The first thing I suggest is moving documentation from GitHub Wiki to the website:

  • It's properly versioned
  • It's easier to modify it for contributors
  • It can be edited locally, with a proper code editor
  • It would have more user-friendly interface
  • We would be able to add some interactive features, like embedding playground to docs (see 💌📯 Updates microsoft/TypeScript-Website#130 for more examples)

One thing that has to be decided is a static site generator we're going to use. I've checked out most of popular JS generator, and I think the best ones we can choose would be either Gatsby or Docusaurus. Docusaurus supports more things out of the box, but Gatsby has a rich plugin system, making it easier to customize.

Another thing I propose is moving website/documentation to this repo. That's a more controversial change (though that's a quite common practice), and it has it's tradeoffs, but there are a bunch of advantages as well:

  • It makes it even more easier to modify it, because adding a feature and documenting it can be done in one PR
  • It's much easier to do playground deployment previews for PRs, which is very useful for previewing changes without local checkout (we would be able to do it like Prettier does, otherwise we'll have to write a bot to do that)
  • It has full access to raw code, so it would be easier to generate API documentation from JSDoc
@ark120202 ark120202 added the docs label Dec 31, 2019
@Perryvw
Copy link
Member

Perryvw commented Jan 1, 2020

I think it makes sense to look at alternatives to the wiki. Having docs in this repo makes sense. We still want to deploy to typescript-to-lua.github.io though, which has to be done through the GitHub pages of the other repository. How are you planning on doing the deployment? I would VERY much prefer if we could restrict the docs in this repo to just markdown.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants