Contributing to Elixir Documentation: My Journey with PR #14501

Have you ever been bitten by a silent nil in Elixir? I have—and it led me to submit a PR to Elixir's documentation. What started as a frustrating debugging session turned into a valuable learning experience about both Elixir and effective technical writing.

While reading the Elixir documentation and exploring its ecosystem, I found an opportunity to improve the documentation about an important anti-pattern - non-assertive map access. This article shares my experience submitting PR #14501 and the valuable lessons I learned about effective documentation through collaboration with Elixir's core team.

The Non-assertive Map Access Anti-pattern

In Elixir, accessing map values can be done in two main ways:

1. Static access (map.key): Used when a key is expected to exist. If missing, it raises a KeyError.
2. Dynamic access (map[:key]): Used for optional keys. Returns nil if the key doesn't exist.

The "non-assertive map access" anti-pattern occurs when developers use the dynamic map[:key] notation for keys that should always exist. This leads to subtle bugs, as nil values silently propagate through the system instead of failing fast, causing errors later and in unexpected places.

My Documentation Enhancement Process

Identifying Opportunities for Improvement

The existing documentation explained the concept, but had room for enhancement:

• It lacked a clear comparison of the available map access methods
• The example code didn't fully demonstrate error propagation
• It didn't provide a comprehensive summary of available approaches

My solution included adding a comparison table, enhancing the examples with error propagation, and providing a clearer summary of the different access approaches.

The Collaborative Review Process

One of the most valuable aspects of contributing to open source is the feedback from experienced maintainers. After submitting my PR, I received thoughtful reviews from @sabiwara and José Valim (@josevalim) that taught me a lot about effective documentation.

Core Team Feedback

José Valim provided valuable guidance that refined the contribution:

1. Focus on the specific anti-pattern:

"I prefer to keep it focused on access vs dot notation for now, as the goal is to focus on the anti-pattern rather than be a complete reference."

1. Avoid redundancy:

"We already have a table above that consolidates the information plus a summary at the end, so I would prefer to put all relevant there."

1. Simpler is often better: > "...I don't want to get too deep into this here. :)"

José suggested removing some of my additions while keeping the core improvements. This feedback wasn't about rejecting my work, but about ensuring the documentation remained focused and maintainable.

The Final Result

The merged PR significantly improved the documentation with several key enhancements:

1. A clear comparison table for map access notations:

   | Access notation | Key exists        | Key doesn't exist | Use case                                         |
   | --------------- | ----------------- | ----------------- | ------------------------------------------------ |
   | `map.key`       | Returns the value | Raises `KeyError` | Structs and maps with known atom keys            |
   | `map[:key]`     | Returns the value | Returns `nil`     | Any `Access`-based data structure, optional keys |

1. Extended examples showing how errors propagate
2. A bullet list of benefits for assertive access
3. A concise summary of different approaches

The final version was more focused than my initial proposal, but also more impactful and aligned with Elixir's documentation style.

Lessons Learned About Effective Documentation

Through this process, I learned several valuable lessons about creating effective documentation:

1. Clarity is the Absolute Priority

The maintainers emphasized keeping explanations simple and focused on the specific concept. Documentation should address a clear question or problem rather than trying to cover everything.

2. Focus on the Essential, Not Every Edge Case

José's feedback helped me understand that good documentation isn't about covering every possible scenario, but about explaining the core concept in a way that helps developers understand the underlying principles.

3. Use Visual Elements Strategically

The table comparing access notations was kept because it provided immediate visual clarity on the differences between approaches. Visual elements should be used when they genuinely enhance understanding.

4. Concrete Examples Matter

My examples showing how errors propagate were retained because they demonstrated a real problem that developers might encounter. Concrete, practical examples are often more valuable than abstract explanations.

5. Collaborative Refinement Improves Quality

The final documentation was better because of the collaborative review process. Each round of feedback helped focus and refine the content.

Tips for Contributing to Elixir Documentation

If you're considering contributing to Elixir's documentation, here are some tips based on my experience:

1. Study the existing style: Before making changes, understand the tone and approach of the current documentation.

2. Focus on specific improvements: Small, focused PRs are more likely to be accepted.

3. Be receptive to feedback: Maintainers have deep knowledge of both the codebase and documentation needs. Their feedback is invaluable.

4. Remember the primary goal: Documentation exists to help developers understand concepts and solve problems. Keep this purpose in mind.

5. Explain why, not just how: Good documentation explains the reasoning behind practices, not just the syntax.

Conclusion

Contributing to Elixir's documentation was a rewarding learning experience. While my initial proposal underwent significant refinement through the review process, the final merged PR significantly improved the documentation.

The process taught me that effective technical documentation isn't about cramming in every detail, but about clearly communicating core concepts with just enough context and examples to help developers truly understand. It's a collaborative process where feedback from experienced maintainers helps refine and focus the content.

If you're considering contributing to open source documentation, I encourage you to take the leap. The process of receiving feedback and refining your contribution is itself an invaluable learning experience.

Have you contributed to open source documentation? What was your experience like? I'd love to hear your stories in the comments!