Skip to main content

Open Source projects and documentation

I am a strong supporter of Open Source since a long time. I understand that the Open Souce movement is important to promote the knowledge sharing in a very wide audience, that it has helped (and it's still helping) to speed up the progress of the IT world and that it brought benefits in terms of quality to the commercial products too. But there is a plea I'd like to do to all the Open Source project holders: please add some documentation to your project. A lot of Open Source projects still suffer of the following lacks:

  • Missing or poor documentation. In the last months I found some potential helpful libraries or plugins (most part of them hosted on GitHub) for the projects I was working on, but no documentation at all or just a short description of the project and nothing else. I know I could browse the source code (I like to do so and add some contribution or send some feedback to help improving something if possible), but at the end I spent less time to implement a solution by myself than go through thousands of lines of code and maybe at the end discover that the library hasn't all the features I was looking for. In most cases there were no code examples or unit tests too. I know that contributors to Open Source projects sacrifice part of their time to them and I really appreciate this, but putting no documentation to their OS projects makes useless all the effort they did because most people couldn't benefit of the project and couldn't contribute to improve it. I also noticed that this problem affects in particular JavaScript OS projects (not only JavaScript, but the percentage is higher for projects in this language).
  • Out-of-date build files. I like to download the latests source code of an OS project that caught my attention and build it by myself. But often happens that the build files (Ant, Maven, Gradle, make, etc.) are out-of-date or incomplete. So one need to understand how to fix them before using a library or a plugin. This situation is often associated with the lack of documentation. Some projects provide also the binaries along with the source code, but some others don't. So please check and update the build file after any new commit.

That said: long life to Open Source ;)
Labels:

Comments

Post a Comment

Popular posts from this blog

Exporting InfluxDB data to a CVS file

Sometimes you would need to export a sample of the data from an InfluxDB table to a CSV file (for example to allow a data scientist to do some offline analysis using a tool like Jupyter, Zeppelin or Spark Notebook). It is possible to perform this operation through the influx command line client. This is the general syntax: sudo /usr/bin/influx -database '<database_name>' -host '<hostname>' -username '<username>'  -password '<password>' -execute 'select_statement' -format '<format>' > <file_path>/<file_name>.csv where the format could be csv , json or column . Example: sudo /usr/bin/influx -database 'telegraf' -host 'localhost' -username 'admin'  -password '123456789' -execute 'select * from mem' -format 'csv' > /home/googlielmo/influxdb-export/mem-export.csv
6 comments
Read more

jOOQ: code generation in Eclipse

jOOQ allows code generation from a database schema through ANT tasks, Maven and shell command tools. But if you're working with Eclipse it's easier to create a new Run Configuration to perform this operation. First of all you have to write the usual XML configuration file for the code generation starting from the database: <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <configuration xmlns="http://www.jooq.org/xsd/jooq-codegen-2.0.4.xsd">   <jdbc>     <driver>oracle.jdbc.driver.OracleDriver</driver>     <url>jdbc:oracle:thin:@dbhost:1700:DBSID</url>     <user>DB_FTRS</user>     <password>password</password>   </jdbc>   <generator>     <name>org.jooq.util.DefaultGenerator</name>     <database>       <name>org.jooq.util.oracle.OracleDatabase</name>     ...
Post a Comment
Read more

Turning Python Scripts into Working Web Apps Quickly with Streamlit

 I just realized that I am using Streamlit since almost one year now, posted about in Twitter or LinkedIn several times, but never wrote a blog post about it before. Communication in Data Science and Machine Learning is the key. Being able to showcase work in progress and share results with the business makes the difference. Verbal and non-verbal communication skills are important. Having some tool that could support you in this kind of conversation with a mixed audience that couldn't have a technical background or would like to hear in terms of results and business value would be of great help. I found that Streamlit fits well this scenario. Streamlit is an Open Source (Apache License 2.0) Python framework that turns data or ML scripts into shareable web apps in minutes (no kidding). Python only: no front‑end experience required. To start with Streamlit, just install it through pip (it is available in Anaconda too): pip install streamlit and you are ready to execute the working de...
12 comments
Read more