Michael - any input here on merging doc -> README.md?, or if we do this how translations should go?
e.g. README.md, doc/fr/README.md On Mon, Feb 24, 2014 at 3:27 PM, Lisa Seacat DeLuca <ldel...@us.ibm.com>wrote: > README.md merge +1 > > I understand the idea behind keeping the documentation outside of the > README.md but given that the "how to contribute" and other info is > generally the same across all of the plugins and is available on the wiki, > etc. it's probably redundant to put it in each repo as well. That being > said it probably wouldn't hurt to have a link on the top of the README.md's > pointing back to the main cordova project info. > > > 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: Steven Gill <stevengil...@gmail.com> > To: "dev@cordova.apache.org" <dev@cordova.apache.org> > Cc: Lisa Seacat DeLuca/San Francisco/IBM@IBMUS, Michael Brooks < > mich...@michaelbrooks.ca> > Date: 02/24/2014 03:08 PM > Subject: Re: [Input request] Rethinking Plugin docs > ------------------------------ > > > > I personally think we should merge the two into README.md. Our readme files > in the plugins are useless right now. Might as well combine some of the > info that should be in the readme + index.md so we have all of the > important information shown prominently. > > > On Mon, Feb 24, 2014 at 11:53 AM, Andrew Grieve <agri...@chromium.org > >wrote: > > > +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. > > > >> > > > > >> > > > > >> > > > >> > > > > > > > > > > >
