cordova-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Max Woghiren <m...@chromium.org>
Subject Re: Pointing docs to edge
Date Mon, 14 Jul 2014 18:31:12 GMT
There's probably a better place for that information.  Also, in practice,
you can imagine how "coming soon" documentation could be kind of clunky,
especially in cases where it's just a behavior change ("right now, X does Y
and Z; soon it will do K as well, and M instead of Y").

I'm sure such changes could be worded more nicely, but that's maybe an
unfortunate concern to pin on someone who's making the change.  Saying
"make the documentation change in the relevant branch" instead of "find a
way to neatly explain that the change is coming soon" would probably do a
better job of encouraging documentation maintenance.


On Mon, Jul 14, 2014 at 1:30 PM, David Kemp <drkemp@chromium.org> wrote:

> I would prefer to have the 'coming soon' stuff more visible.
> I like the idea that when looking for how to do something, its easy to see
> improvements that have already landed - and I can possibly get just by
> grabbing a bleeding edge plugin/tool.
>
>
>
> On Mon, Jul 14, 2014 at 1:25 PM, Max Woghiren <maxw@chromium.org> wrote:
>
> > I agree.  I think 3 is my preferred option; I think it lends itself best
> to
> > a sustainable and straightforward workflow.
> >
> > Docs fixes relevant to the current release of the CLI and each platform
> can
> > be committed directly to master.  Unreleased changes can be committed to
> > the appropriate branch, and we can add the merging of the branch as a
> step
> > in the release process.
> >
> >
> > On Mon, Jul 14, 2014 at 1:06 PM, Ray Camden <raycamde@adobe.com> wrote:
> >
> > > Personally I'd rather not have any "coming soon" paragraphs in the doc
> > > text. As a user, if I'm at the docs, I don't care what is coming next.
> > I'm
> > > trying to solve a problem I have *now*, or trying to build now.
> Anything
> > > that is coming soon is a distractor.
> > >
> > > Do I feel strongly about it? No, but I'd vote against it being in the
> > docs
> > > at all. Stuff like that should definitely be communicated to users -
> via
> > > the Cordova blog perhaps - but not in the mainline docs.
> > >
> > > ________________________________________
> > > From: maxw@google.com <maxw@google.com> on behalf of Max Woghiren <
> > > maxw@chromium.org>
> > > Sent: Monday, July 14, 2014 10:27 AM
> > > To: dev
> > > Subject: Re: Pointing docs to edge
> > >
> > > Okay, so here are the current proposals for handling Ray's issue
> (thanks
> > > Ray!):
> > >
> > > 1. Update docs at commit-time and release-time.  At commit-time,
> > > documentation changes can be marked with "coming soon", or "removed in
> > next
> > > release", or whatever the relevant message is.  At release-time, docs
> are
> > > further updated to remove these sub-messages.
> > >
> > > 2. Use CSS to do the manual marking in proposal 1.  We could also use
> it
> > to
> > >
> >
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message