Documentation in opensource

Documentation in opensource

Importance

It is obvious that with detailed and well-explained documentation, contributor will definitely have a easier time with the environment set up and a good overview about how the project is structured which is really saving a lot of time.

Commenting

Besides documentation, code with clear comment also help developers reuse some of the existing code easily. I believe that no programmers love to read 10 thousand lines of code just to figure out where a variable is being defined. Following good commenting standard makes your code so clear to others about what the code is about, what does it do and how it is being used. For instance, giving description of the parameters and return values of a function is considered a good commenting standard, especially in open-source projects.


Working with thimble 

Currently I am working on the thimble project from github. The feature I was trying to add is a inline-border-radius editor. The documentation provided by the repo maintainer is very well-documented. They had a section in their readme file for adding extension. In that section, everything I need was provided, even little details are being explained very clear.

Thoughts

Working on a open-source project does not always means coding, but more likely, making contributions to the community and helping each other. Making the code clean and well documented should be one of the skills a programmer must have. If everyone can try their best to do it, the community will definitely be improved.  

Comments

Post a Comment

Popular posts from this blog

Image
Augmented Reality in Industrial Safety Augmented Reality is already improving worker performance  This is a interesting article talking about how AR improves industrial workers' performance, variousexamples are used to demonstrate  how AR technologies can be applied in industrial activities  https://hbr.org/2017/03/augmented-reality-is-already-improving-worker-performance 4 Applications in 2018 for augmented reality in construction Augmented Reality is a emerging technology being used in many domain areas, construction is one of the field that may be influenced by AR in the future.  https://esub.com/4-applications-in-2018-for-augmented-reality-in-construction/ Ontario ministry of labour- health and safety Many Health and safety related records can be found here. This site contains reports about the injures or fatalities recorded each year in Ontario labour force.  https://www.labour.gov.on.ca/english/hs/index.php Augmented Reality in Construction
Read more

Second release on thimble

Image
This week I was working on my second bug on the thimble repo. This one is a feature request. Here is the link to the issue https://github.com/mozilla/thimble.mozilla.org/issues/2506. I basically need to add a inline editor for editing the Border-radius css rule. Something like this: I already made it partially working. But some of the UI style still need to be fixed. As you can see right now the background color is all read which does not really meet the production level standard. At the first glance of the issue. I didn't think this should be taking too long, because there are already some existing inline editors code example. I thought I can just do bunch of copy-paste to make it work. However, when I really sit down and starting working on it, it was totally different than what I thought. You need to have different files to handle different behaviours of the editor. To figure that out I started by reading the existing code over and over again. That took me a long time to g
Read more