intellij-sdk-docs

intellij-sdk-docs copied to clipboard

Some things to discuss so far:

• [ ] showPaidPluginWarning description does not explain why this is needed. It just explains what it does, which everyone can guess from the name already.
• [x] Sometimes, we have task descriptions starting as real sentences like "This is a task used to..."; other times, we just write "Prints the list of...". What form should we use consistently?
• [ ] verifyPluginConfiguration Is it correct that this task validates that "The currently selected Java Runtime is not JetBrains Runtime (JBR)"?
• [x] We are inconsistent and use paragraphs basically as bullet points. E.g. these are not full sentences but they could be one paragraph which I would much prefer. Can we make this consistent?

My opinion:

showPaidPluginWarning description does not explain why this is needed. It just explains what it does, which everyone can guess from the name already.

+1; it would be nice to explain the purpose.

Sometimes, we have task descriptions starting as real sentences like "This is a task used to..."; other times, we just write "Prints the list of...". What form should we use consistently?

I think we should use more concise form, so "Prints the list..." instead of "This task prints the list...". This style is used in, e.g., method Javadocs, which I think are analogical to task descriptions on our pages.

We are inconsistent and use paragraphs basically as bullet points. E.g. these are not full sentences but they could be one paragraph which I would much prefer. Can we make this consistent?

~~I don't understand. It looks good to me, but I don't get the lack of the period in the second one. Could you please provide an example sentence?~~ OK, started reviewing and see it now. Your version looks better, IMHO.

Please note that some texts need to be synced with kdoc in the plugin itself.

Thanks!