How do we make our software more understandable, transparent, efficient and generally usable by developers? Good designs should be self-explaining, but in a complex system that's easier said than done.
There are many small things that influence this, as well as architectural decisions where one might trade off other criteria for developer usability.
I find it captivating to try and improve things so that people understand them better - I'll try to find out more about what makes the difference here, but for now I've made a few suggestions related to documenting Sling, which would hopefully apply to other projects as well.
(Update: see the next post for a more general view on those suggestions).
I'm starting to think that documentation is like code comments: if you need lots of it, that's a bad sign.
Feedback is welcome.