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.
Yes, I hit documentation I donât understand quite often. The best experiences Iâve had getting through these issues are just going into a packageâs Gitter channel and just start discussing how to do it, and why the API is like that. Once I understand it, I submit a PR to the documentation.
That last part is crucial. Please submit PRs to documentation the moment you understand it! You are in the best position to know what itâs like to not know what you just learned! Itâs almost impossible for someone well-versed in a package to accurately assess the mind-state of âwhat itâs like to not knowâ and write good docs.
If you donât want to join a chat, I think opening an issue is great as well. Donât be mean, but say âHey, I donât understand this part of the docs. Could you explain this to me in a different way?â. It might take a few tries, but in the end youâll learn it, and this will likely empower the author (or you!) to make the change to the documentation to help others.
Documentation is an iterative process, and it only improves as each individual does their part to make it easier to understand.
Please submit PRs to documentation the moment you understand it! You are in the best position to know what itâs like to not know what you just learned!
In honor of international womenâs day, I thought it might be apropos to include a substantially incomplete list of some women and grandmas who donât need any additional help understanding docs.
@TravisA9, out of curiosityâthis is not my position, but itâs a counterargument I could imagineâwhat would you say to the argument that âthereâs a tradeoff between progress on code and progress on documentation, you get to choose a point on the efficient frontier, e.g. fast progress on code with poor documentation, moderate progress on code with moderate documentation, or slow progress on code with excellent documentation, and we at [insert package or community] have chosen âfast progress w/ poor documentation.ââ
What do you think? Can someone make the case for a particular point on this efficient frontier as being âbetterâ for some reason? E.g. fill in the details in one of these arguments:
âFast progress + poor docsâ is better overall, because (say) the experts can start using the code right away, and the docs can always get filled in later for the slower learners
âSlow progress + great docsâ is better in the long term, because (say) code changes over the long term are more driven by large-scale design decisions that emerge from user engagement than from progress on rapidly iterated features
Or something
Any thoughts? I appreciate the initial question and am just curious what the experts in the dev community (and others) think about this.
Disclaimer: I am probably as unqualified as anyone to attempt to answer this.
@philip, personally, I think that questions like the one you asked and perhaps also the initial question may not have one easy answer. The best choice may have a lot to do with circumstances. But I think it is important to periodically raise the question to see if new knowledge or a change in circumstances might lead to a need to make adjustments or improvements. I have worked as a teacher for a long time and have often scolded students for criticizing others for âstupid questionsâ but I think that it is great to revive some basic questions to see if someone has come up with a novel solution or perspective.
One of the reasons that I even took a look at julia was because I had changed one of my basic ideas. I used to say: âdonât re-invent the wheelâ as many people say. But I have a very different perspective on things now. Julia is a great example of that. Too often big projects get caught in a local minima and cannot advance beyond that. By starting from scratch, not only do you learn a lot but things almost invariably work out better the second time.
To answer your question, I used to write tones of code with very little or no documentation but as time goes on I am constantly doing more commenting and documenting. By writing the docs I give myself the chance to reflect on the state and progress of my work and begin to remember where I am headed and what I forgot to do. âŚstill I think I could improve.
