How to contribute to Electron documentation

Having read some of the documentation, it isn’t clear to me how suggestions to improve the documentation should be presented or where they should be discussed, preliminary to submitting a pull request.

I am new to Electron, having first seen it only a few days ago. I am trying to use it to build an app and, to this end, exploring the documentation, examples and code. I have had some difficulty finding information I have looked for in the documentation and would like to suggest some changes that would have helped me and might help others to come.

Aside: apologies but being a new user I am only allowed to put two links in a post. I have broken the links below to circumvent this limitation without making the documents I refer to too difficult to find.

I read wwwelectronjsorg/docs/tutorial/support, which led me here.

I read wwwelectronjsorg/docs/development/issues which indicates that the issue tracker should be used to report bugs only. Suggestions for enhancing the docs aren’t bugs, so I have not opened any issues to suggest enhancements, though I did submit one bug report for a broken link in the docs on the assumption that a broken link in the docs is a bug of sorts, though not a bug in electron itself.

In submitting that issue I was referred to various docs including githubcom/electron/electron/blob/master/CONTRIBUTING.md, which I reviewed. It said nothing about how to suggest enhancements of any sort.

I noticed the Improve this doc link on the bottom of some pages, but these merely take one to the corresponding files in the GitHub electron/electron repository, with no guidance as to how the team would like suggestions to be submitted.

I found wwwelectronjsorg/docs/development/pull-requests and I could simply submit a pull request for document changes without any preliminary issue or discussion, but it isn’t obvious to me that this is the preferred approach.

I found githubcom/electron/electronjs.org/contribute, not through the Electron docs but via Google search. And from this page I followed the link to githubcom/electron/electronjs.org/blob/master/CONTRIBUTING.md. Contrary to the issues doc referred to above, this says “If you’re not sure about adding something, open an issue to discuss it.”, which suggests that issues are not only for bugs. It does say “Feel free to open a Pull Request early so that a discussion can be had as changes are developed.”, so perhaps the best way to present my ideas for improving the docs is by submitting a pull request without any preliminary discussion. If I have ideas for simple changes, for which I can prepare a pull request without too much effort, I suppose I will do that.

But I would be interested to hear what the team prefers - how I can be most helpful and least bothersome?

For trivial changes, if I think I know how the docs should be changed, I will simply submit a pull request. For non-trivial changes, I would not like to do hours or days of work to prepare a pull request only to have it rejected. I would like to know where ideas for such changes should be presented and discussed prior to preparing and submitting a pull request.

1 Like