A case for writing understandable and accessible documentation

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 :sunglasses:


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!

Definitely a good point!

1 Like

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. :wink:

Grace Hopper:

Fran Allen:

Barbara Liskov:

Sophie Wilson:

Jean Bartik



grandmas who don’t need any additional help understanding docs.

Well called! Thanks for pointing that out :blush:

@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.

1 Like