On occasion I answer a question on stackoverflow, the discussion forum or elsewhere and I get a response of the form of: "this wasn’t clear from the docs". We improved the docs but befitting a huge project run by engineers without a technical writer in sight this is a bit of a problem… The thing is that this is a problem you can fix regardless of your level in engineering or in English.
The benefits are pretty cool:
You have a pull request in your name
Documenting stuff helps understand the nuance and makes you a better programmer
We would really appreciate it
That’s a lot for something that’s so trivial to accomplish!
Fixing the JavaDocs
Fixing the JavaDoc for a class couldn’t be easier. You need a github account (which is free) you can then go to https://github.com/codenameone/CodenameOne and type in the search bar the name of the file you want to fix in the javadoc e.g. if you want to improve the JavaDoc for component just type:
filename: prefix for a quicker find…
You should see something like this:
Figure 1. List of component classes the first one is what we are looking for
When we enter we first must select the master branch in the combo box then we can press the edit button on the top right:
Figure 2. The combo box to select the master branch and edit button for the source file
You’ll get a couple of standard notices:
Figure 3. Standard notices
Find the method whose JavaDoc you want to edit and just edit it. Once you do that scroll all the way down and enter a description in the propose file change box and submit it:
Figure 4. The propose change box, make sure to describe your change briefly
Once you click propose change you can make it into a pull request and thus submit it to us. This takes two clicks on green buttons and literally nothing more.
Figure 5. First stage of pull request you are prompted with the diff of the change you made
Figure 6. Second stage of pull request you can edit the submit comment
We usually accept simple pull requests pretty quickly. Please feel free to submit. Once you go thru that process it becomes trivial and helps you dive deeper into the code.
Edit the Developer Guide
This is actually easier. You can just open the developer guide and edit it without a pull request as it’s hosted in our project wiki!
You can open it here or by clicking the wiki tab in the Codename One github project. The edit button on the top right allows you to edit the document instantly and save it directly to the project.
The one hurdle is that the guide is written using asciidoc which is a simple language but if you aren’t familiar with it then it might take a couple of minutes to understand. You can just follow the conventions in other parts of the guide to get started.