Hi all, I just wrote a note in https://issues.apache.org/jira/browse/KAFKA-2967 with a proposal for changing how docs are written. I want to move on this soon if possible and normally would just leave the discussion to the JIRA, but as I think this is something everyone has an opinion on and affects everyone contributing to the project, I figured I'd send this quick note to increase the likelihood people see it and have a chance to weigh in.
Thanks, -Ewen
