Ask JB: How to contribute to the IntelliJ Platform SDK Documentation
Our Gitter Chat took off extremely well and I have learned many things already. One criticism that Serge pointed out about the chat was that valuable information might get lost in a chat while they are preserved and indexed on the community pages. I feel exactly the same and asked in our chat where we should save information and tips for future visitors. Basically, we see two good options:
- We write how-to's and faq's for the official IntelliJ Platform SDK Documentation site
- We maintain a GitHub wiki or gh-pages bases website
The people I spoke to would prefer to include such documents in the official SDK documentation and I generally feel the same way. It has an implicit downside though: Free-time plugin developers often have the feeling that they don't see the whole picture on a topic. Therefore, although I like to share my knowledge about say "setting up a cache for references", I might hesitate because I'm not sure what I do is best practice. Additionally, writing for the official site will increase the workload of reviewing for JB; at least a bit. I wouldn't have these doubts when writing for a self-maintained wiki. People could either use the advice or ignore it.
There is a third option: We could pull off our own wiki and if we indeed manage to come up with some interesting how-to's, we can easily include them into the SDK docs. After all, it's just markdown. This would have the advantage that those documents can easily be edited and previewed online and there is no need to understand the SDK doc Jekyll structure (although this is not really hard) or clone the SDK doc repo locally.
Question: What is the opinion of JB about this?
Edit:
In the meantime, I created a draft of how I think a "user created doc" subpage can look. The advantage is that it will cover very specific topics like "What is a LightElement" or "Can I parse plist files".
Please sign in to leave a comment.
Firstly, this is brilliant, thank you! I'm responsible for the SDK docs and to be honest, I'd love to see content from the community being added. The IntelliJ Platform is a huge thing to try and document, so the more contributors, the better, in my opinion. Of course, if you'd prefer to have a simpler workflow, and contribute to a user owned wiki, then that's cool too, but I'd love to have content in the SDK docs.
I wouldn't worry about adding to the review workload - that's a nice problem for me to have :) I can arrange for pull requests to be reviewed and help with any changes required to get them merged. Likewise, don't worry about writing for the "official" docs - any issues or incorrect assumptions can get resolved as part of the review.
So, from my perspective, fire away with pull requests!
That's great, thanks Matt. That could be very helpful for those of us working with the platform - if we can submit doc pull requests and get them reviewed and updated, that's a useful way for us to learn too. I agree that all this content should be in the SDK docs somewhere, too.