Contributing to Documentation
Hi, I’ve been trying to find a way to contribute to the official documentation (fix small typos, links, etc) but I haven’t found a way yet. Is there any available contributing guide to the docs?
Please sign in to leave a comment.
Hello Pedro,
thank you for the initiative. I see value in what you are proposing. I'm afraid, however, that this is currently not possible. A decision has been made some time ago to leverage the proprietary technology and internal processes that other JetBrains tools use for documentation. Also, the documentation sources are co-located in a private repository with the other JetBrains tools (after all a great portion of the MPS documentation is taken from the platform).
This leaves external contributors with two options:
1. The per-page comment capability in the documentation.
2. The "documentation" subproject for new issues in youtrack (https://youtrack.jetbrains.com/newIssue?project=MPS)
Best regards,
Vaclav
In the end of each page there is a question "Was this page useful". You can select "No" and write a comment. This comment will be recieved by the MPS team as a documentation issue. Another way is to submit an issue in MPS youtrack project and assign the issue to the Documentation subsystem.
Thanks for the answer Maria. Wouldn’t it be possible to make the documentation open by shoving it in the MPS repo under /docs or someplace else, and allow to be contributed just like many other OSS projects do?
The amount of benefits are innumerable compared to the current format.
Thank you for the answer Vaclav.
Still, if I could provide some feedback, it would be that the current format deters external contributors wishing to make any substancial work, and it isolates a source of truth into internal and proprietary processes which goes against the OSS ethos.
It would be interesting to see that change in the future, just having the documentation freely available within the MPS repo as a primary source of truth would be a nice change, even if the documentation output would still be rendered in the proprietary JetBrains Platform.
Hi Pedro,
I've stated almost the same but with respect to forum/Slack issue, maybe some years ago when the Slack channels started. In fact this forum is almost dead and today the Slack channels are the main channels to ask for help, I mean.. where most (all) of the MPS users ask for help.
I would not mind to use Slack if this "main source of documentation" would not get lost after a while, unless you are a paying Slack user. And this forum is the minimal forum I've probably ever seen. Documentation is the same: with the availability of markdown editor, wikis, restdocs, git ecc, for improvements the MPS documentation rely on comments. Isn't that interesting? I mean I would expect all this from a completely non-technical community... like cooking or scuba-diving.
So... I don't understand this but you know the OSS world is free. So JetBrains is free to organize this forum or the documentation as they prefere and you are free to start an MPS documentation project if you want. In fact I don't have time right now (I contrinuted to the old MPS documentation, you can still see an howto about pluging and PlantUML) but one day I could start an "MPS Documentation Addendum", and it will be perfectly fine. Then someone will probably publish "Awesome MPS" to resume all the interesting projects scattered around (smile)
Check out http://mbeddr.com/mps-platform-docs/ by Alexander Pann.
Check out https://mps.rocks/ by Kolja Dummann.