Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docco-style documentation #352

Closed
chenglou opened this issue Sep 16, 2013 · 1 comment
Closed

Docco-style documentation #352

chenglou opened this issue Sep 16, 2013 · 1 comment

Comments

@chenglou
Copy link
Contributor

#351 cleans up lots of categorization nits and made the docs cleaner. Thanks to that, some of the old sections can now be reduced to a few sentences. I was thinking of taking this occasion to:

  1. Fully comment the examples so that it can be processed through Docco.
  2. Potentially replace those dangling documentation sentences with fresh, fully-featured examples that do the walkthrough while explaining various points (from the current docs). One example I raised in IRC is that "components are just state machines". Seeing that the whole event explanation above now has its dedicated section, these sentences can be reduced to comments in the said examples.
  3. Maybe even better than just Docco, display the live editor side-by-side (or whatever UI works) so that the user can see the example code, play with it while reading the comments beside, and still have a complete ref to the API nearby. At the same time this ensures the examples are well separated into chunks. Imagine a front page, but with examples and comments as docs. This idea is really just a demo of the kinds of things we could do; not saying it should be this way.

1 is a non-brainer even without the Docco processing part; I'm down to do it. I can even design some new examples to replace/complement the old ones so that they expose React's general ideas rather than just demoing small snippets of components. This should eliminate another chunk of the documentation. These examples can live in the repo and the doc page.

The goal I'm thinking of here is to be able to tell people what React is through only examples and API docs, no extra explanation needed. At the end of the day, there shouldn't be much documentation left outside of the examples and the API docs. There are flaws in this approach, mainly that the narrative will have to be from the top to the bottom of the code; but I think React's nature alleviate this. I really have to show an example (thinking of starting with the existing comment ex) to prove this.

And hey, if there are details that don't fit into example comments, cookbook's still there.

I realize this is ambitious, but it seems appealing enough to be suggested. I really believe a good example can eliminate lots of explanations and this is an approach I've taken for my own repos; they seem to work well so far.

@chenglou
Copy link
Contributor Author

chenglou commented Jan 1, 2014

Closing this for now because the changes to the examples can be done gradually

@chenglou chenglou closed this as completed Jan 1, 2014
bvaughn pushed a commit to bvaughn/react that referenced this issue Aug 13, 2019
* Updated local fork of react-window
* Updated Fow 97 -> 103
* Lint ignore NPM dist
* Improved Bridge Flow types
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant