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

Working with gh-pages

Image
Hosting This week, we were introduced to the "gh-pages" which is one of the  coolest feature on github that enables you to host your static web content on github for free! the setting up for this is very simple, you only need to create a repo using your github account and then add master or the gh-pages branch to this repo then you can commit and push your html or any web content related files onto your master/gh-pages branch then your website will be available on github. After many researches on where to host your website, I think gh-pages may be the best option for me, simply because I don't want to spend a penny for hosting my website. This is just a simple static html file I put on my github host. Right now the domain name is using the github defaut standard, and you can actually customize that domain name in the settings tab under your repo. Code Reading Basically, this page is a static page that display a result of a test on the onload event of a ima tag.
Read more