on plugman publish: if (exists docs/en/README.md) use that; else use README.md;
?? The reason I suggest that is because I think relative links will not work very well if we have the EN docs at a different level than the other languages. -Michal On Wed, Mar 5, 2014 at 2:50 PM, Andrew Grieve <[email protected]> wrote: > That's a hairy point of this change for sure. Not sure what the best would > be. Maybe treat doc/fr/README.md as based on /README.md > I think the majority of third-party plugins will write only README.md, and > have no doc/ at all, so having it be a special case is worth it I think. > > > On Wed, Mar 5, 2014 at 2:44 PM, Michal Mocny <[email protected]> wrote: > > > How does that work with proposal for i18n? Ideally the docs/ tree is > > identical in each language, so I think we want the top level docs > > (README.md or index.md) to be in the docs/en/ tree as well. > > > > Perhaps we leave the README.md empty and change plugman publish to bundle > > docs/en/index.md instead? > > > > Or perhaps we make README.md == docs/en/index.md always? > > > > -Michal > > > > > > On Wed, Mar 5, 2014 at 2:25 PM, Andrew Grieve <[email protected]> > > wrote: > > > > > The discussion so far has been: > > > - npm, github, surface README.md prominently > > > - our README.md files are essentially empty > > > - let's delete doc/index.md and put it all in README.md > > > - plugins.cordova.io will render the README.md prominently > > > > > > > > > On Wed, Mar 5, 2014 at 1:25 PM, Michael Brooks < > [email protected] > > > >wrote: > > > > > > > Andrew, do you mean merging all of the documentation into the > README.md > > > or > > > > do you mean translating the README.md to other languages? > > > > > > > > > > > > On Tue, Mar 4, 2014 at 10:05 AM, Andrew Grieve <[email protected] > > > > > > wrote: > > > > > > > > > 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 < > > > [email protected] > > > > > >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 | *[email protected]*< > > > > > [email protected]>| | > > > > > > *[email protected]* <[email protected]> | *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 <[email protected]> > > > > > > To: "[email protected]" <[email protected]> > > > > > > Cc: Lisa Seacat DeLuca/San Francisco/IBM@IBMUS, Michael > > > Brooks > > > > < > > > > > > [email protected]> > > > > > > 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 < > > > [email protected] > > > > > > >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 <[email protected]> > > 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 < > > > > [email protected]> > > > > > > > > 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 < > > > > > > > [email protected] > > > > > > > > >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 | *[email protected] > *< > > > > > > > > [email protected]>| | > > > > > > > > >> *[email protected]* <[email protected]> | * > 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 <[email protected]> > > > > > > > > >> To: dev <[email protected]> > > > > > > > > >> Date: 02/24/2014 01:41 PM > > > > > > > > >> Subject: Re: [Input request] Rethinking Plugin docs > > > > > > > > >> Sent by: [email protected] > > > > > > > > >> ------------------------------ > > > > > > > > >> > > > > > > > > >> > > > > > > > > >> > > > > > > > > >> On Mon, Feb 24, 2014 at 12:51 PM, Marcel Kinard < > > > > > [email protected] > > > > > > > > > > > > > > > >> wrote: > > > > > > > > >> > > > > > > > > >> > > > > > > > > > >> > On Feb 24, 2014, at 12:32 PM, Andrew Grieve < > > > > > [email protected] > > > > > > > > > > > > > > > >> 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. > > > > > > > > >> > > > > > > > > > >> > > > > > > > > > >> > > > > > > > > >> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > >
