A case for writing understandable and accessible documentation
For different reasons it may be difficult for a person to enter a field or project and get a good enough understanding of how things work to be able to actually contribute. However, at times the greatest contributions are made by persons from outside a community because of their differing knowledge and interests. Communities have been shown to grow faster and be more productive if there is a diversity of interests and knowledge. It often takes many types of expertise to make a good thing great.
To be clear, it can be difficult to keep up on documentation when a project is in full swing. That is another issue entirely! But let’s suppose I’m a brain surgeon and I want to contribute to a project for images I may have vital knowledge to contribute and yet be completely out of my realm of knowledge as far as programming is concerned.
To further complicate the situation we create “black boxes” when programming which are spread across many files and some of that code may also have compiled dependencies; the code of which cannot be viewed. The black box concept is a bit paradoxical because, though it is intended to simplify things, the result is that for others to make meaningful contributions to our projects they have to spend much time and energy searching through files, looking into those black boxes and reading up on the dependencies (not to mention, theory on the subject itself). If they are successful, maybe they will contribute something.
Flux is just one good example in the julia community and there are many more. I commend the makers of Flux and others for their documentation. Many of the things I had to struggle to understand in other frameworks are fairly clear there. I also liked their RNN julia-code generator example.
That’s about the same as what I managed to do using another package after training on 11,000,000 Chars of julia code back in May of 2016. I got good results and wanted to take it to a new level but could not understand the package or its internals well enough to make the needed changes. Although my ignorance is undoubtedly part of the problem, it would have been great if documentation were more thorough. In that case I would likely have made some interesting contributions. As it is, those contributions may end up being a part of Flux.
Have you ever encountered a situation like this? How common is it? How would you improve the ‘barrier to entry’ issue? I would like to hear your thoughts.
EDIT: sorry for the blog!
EDIT 2: more considerate wording