+Michael Might be helpful to write out expanded README.md files for our plugins. Right now, they just contain a title and a link to the docs: https://github.com/apache/cordova-plugin-file
"What it is" is covered by the first paragraph of the docs already I think. "How to contribute" is pretty obvious for most github-hosted projects, but I don't think that would hurt as part of the documentation either. On Mon, Feb 24, 2014 at 2:37 PM, Brian LeRoux <b...@brian.io> wrote: > I think Mike's main consideration is that the README.md is a place for > general project info (what it is, how to contribute, etc) whereas > documentation, inc translations, should be in a dedicated space as standard > convention so we can tool it. (Something like this: `doc/[lang]/index.md > `.) > > > On Mon, Feb 24, 2014 at 11:26 AM, Andrew Grieve <agri...@google.com> > wrote: > > > That was basically the question in my head as I was typing... I'd be > happy > > with having just a README.md, and allowing it to link to relative .md > paths > > if it wanted to. > > > > > > On Mon, Feb 24, 2014 at 2:21 PM, Lisa Seacat DeLuca <ldel...@us.ibm.com > >wrote: > > > >> If README.md is the standard why not just call all of them README and > not > >> have an index.md file at all for the plugins. What is the advantage of > >> having both? Seems more confusing than anything. > >> > >> Lisa Seacat DeLuca > >> Mobile Engineer | t: +415.787.4589 | *ldel...@apache.org*< > ldel...@apache.org>| | > >> *ldel...@us.ibm.com* <ldel...@us.ibm.com> | *lisaseacat.com*< > http://www.lisaseacat.com/>| [image: > >> follow @LisaSeacat on twitter] <http://www.twitter.com/LisaSeacat>| > [image: > >> follow Lisa Seacat DeLuca on linkedin]< > http://www.linkedin.com/in/lisaseacat> > >> > >> > >> > >> > >> > >> From: Andrew Grieve <agri...@chromium.org> > >> To: dev <dev@cordova.apache.org> > >> Date: 02/24/2014 01:41 PM > >> Subject: Re: [Input request] Rethinking Plugin docs > >> Sent by: agri...@google.com > >> ------------------------------ > >> > >> > >> > >> On Mon, Feb 24, 2014 at 12:51 PM, Marcel Kinard <cmarc...@gmail.com> > >> wrote: > >> > >> > > >> > On Feb 24, 2014, at 12:32 PM, Andrew Grieve <agri...@chromium.org> > >> wrote: > >> > > >> > > - We may also want to include README.md files in the translations. > >> > > doc/fr/index.md > >> > > doc/fr/README.md > >> > > >> > What content do you forsee being in README.md other than a > >> > table-of-contents to the languages? Or in other words, would it be > >> > public-facing content that could be collapsed in to the rest of the > >> plugin > >> > docs? > >> > > >> > >> On npmjs.org and on github, README.md's are the files that are shown > most > >> prominently. So, I speculate that many plugins will not provide a doc/ > >> index.md, and instead provide only a README.md. > >> > >> > >> > > >> > > - We don't need the version in the directory since we can use git > >> tags to > >> > > find old versions > >> > > >> > That makes sense. > >> > > >> > > >> > >> > > >