Repository navigation
Adding annotations to API Documentation #7147
Description
We've been talking for a long time about how we can improve the documentation. There's something of a tension between the need for dry technical documentation and more nuanced language that might be better at teaching people. It has also been difficult to get more documentation contributions through the standard core contribution process and there are some good reasons for keeping the actual documentation in the core repo rather than somewhere else.
Genius (formerly Rap Genius) released a pretty amazing annotator for the web. You can annotate any page with the Chrome Extension but you can also just add this to have it work for everyone:
<script async src="//genius.codes"></script>
This would allow people to start writing up more context around various parts of the documentation. When someone is confused by a particular section of documentation we could annotate it, which would show a highlight they can click on, that talks in plainer language.
Thoughts?
Activity
addaleax commentedon Jun 4, 2016
/cc @nodejs/documentation
Fishrock123 commentedon Jun 4, 2016
I am concerned about how easy it may be to troll said annotations.
mikeal commentedon Jun 4, 2016
@Fishrock123 being that it is backed by the same system that Rap Genius uses, it has a system and process for dealing with trolls. Every annotation has a "report abuse" link and Genius has paid moderators that deal with it.
sotojuan commentedon Jun 4, 2016
Cool idea but what does it say about documentation when you need a tool created for abstract/complex lyrics to understand it? I say go for it as long as we look at the annotations people make or parts that people ask about the most and improve those.
gloddy commentedon Jun 4, 2016
Good documentation, like any good writing, is hard. I fear that a tool like Genius, as clever as it is, will simply add noise and distract from the work of providing healthy, understandable materials.
santiagogil commentedon Jun 4, 2016
Why not links to real life examples (contextualized usage) and tutorials?
eljefedelrodeodeljefe commentedon Jun 6, 2016
Can't this be done with some gatekeeping via a PR instead of just letting users do that?
In any case I agree that the documentation can and should have one or two extra dimensions by some visual means such as this.
jasnell commentedon May 30, 2017
Close due to lack of forward progress on this.