nodecg-io
nodecg-io copied to clipboard
codeoverflow-org
Improve documentation
Description
Currently the Wiki is just in this repo and should be moved into a separate repository just like the one of ChatOverflow. It should also be built by a GitHub Actions and be hosted by GitHub Pages.
Progress
- [X] Move docs to new repo
- [X] Create gh actions workflow for automatic deployment
- [X] Create gh actions workflow for automatic generation of dependency tree and services file
- [X] Restructure the wiki
- [x] Add a guide for contributing to the wiki
- [ ] Review all existing pages to make sure they are well structured and easy to understand.
Add clarifications where needed. - [x] Use extensions (like admonition) to improve the overall style and look
- [ ] Make it MINZIG
Do you want to do this? Otherwise I would love to have a look at it as I'm already familiar with the process and it would be a perfect task I could do.
Sure, you can do it @joblo2213. You probably have more experience working with mkdocs than I do.
Why wouldn't you simply serve the docs/ folder instead of creating an extra repo?
Still wondering if we should add a markdown linter.
Generally I realy like the idea of having a linter that looks for style issues in the files, I only wonder how well it works together with mkdocs and the extensions.
Stuff that could be usefull:
- https://github.com/DavidAnson/markdownlint
- https://github.com/igorshubovych/markdownlint-cli
- https://github.com/xt0rted/markdownlint-problem-matcher
I would also like a markdown linter, if it works fine with mkdocs.
The numbering in some sample bundle guides is currently off.
Here is the discord service guide as an example:
There the last both should be 6 and 7, but they both restart counting at one.
Currently each sample doc explains how you get on the dashboard, set a password after first start, create a new service instance and how to set a service instance to a bundle, so it can be used by it. It even mentions the monaco bug, which was only present in the very first versions and that has long been fixed.
This repetition is not great because things might change and you propably don't want to change it everywhere. Instead I would want to have seperate a usage documentation (maybe in the Getting Started tab after installation) which shows you how to login, create and update service instances and set bundles to use a service instance.
The sample docs should imho be centered arround the service and not the sample, because it mostly explains how you can use the service and what config you need to provide. Writing what the sample does with the service and how it is named should be enough.
Actually the ChatOverflow docs are a good example of how I would want them again with nodecg-io. Have a guide how to use the dashboard and then a entry for each service that describes what config it needs and where you can get tokens. Instead of a code snipped I would then explain what the sample does and link to it.