Improving MDN macros by moving to GitHub

[Florian Scholz]

Hello MDN lists,

this is a presentation for an idea that was brewing in the last couple
weeks around a better system for how we work with macros. I collected
some feedback from different people and presented this in the mdndev
weekly planning meeting today.

I would like to use this thread to further iterate on the idea, hash out
more details, and come up with a plan or next steps, if we decide that
want to do this.

https://docs.google.com/presentation/d/1RE4qi047mFAwBChKMg-4CUSe23jFZmRDMbmCX867Bio/edit#slide=id.ge61d748be_2_37

Sending to dev-mdc and dev-mdn as this involves governance questions and
work for both teams (writers and kuma engineers).

Also, we talked about a project called "macro cleanup" in the past. That
cleanup is encompassed here.

Looking forward to more thoughts!
Florian

--
Florian Scholz
Technical Writer
Mozilla Developer Network

[Eric Shepherd]

Florian Scholz wrote:
> this is a presentation for an idea that was brewing in the last couple
> weeks around a better system for how we work with macros. I collected
> some feedback from different people and presented this in the mdndev
> weekly planning meeting today.

I think this idea shows incredible promise! First off, I want to commend
Florian on a well-researched and thought-out proposal, which he
presented to a mixed writer/platform dev meeting today. Nicely done!

The idea of moving MDN macros to Github is an intriguing one. It would
certainly make versioning and coding work easier.

I would like to hear if there are any possibilities on the dev side for
abilities to improve the utility of things like modules (which are a
great idea but underused due to some inherent flaws in how they work,
largely due to problems with the V8 runtime).

My biggest concerns are about the development, testing, maintenance, and
deployment cycle for macros:

* If we're on a fixed deployment schedule, what happens when we have
to fix a bug that's critical, or if we have a project of content
that depends on a macro deployment, which stalls out because of the
deployment schedule. Having to time posting of articles to macro
deployments is not something that's currently feasible; given that
we do develop or update macros based on content changes, this will
be a thing to deal with.
* Before doing something like this, I'd like to better quantify what
benefits we get on the platform side of things if we go this route,
and what the specific challenges of making this change are.
* Macros in development very frequently are being developed or updated
because of needs introduced by or oriented around recent content
changes. This means that macros will have to be able to be tested
against current site content. We'll need a way to test
in-development or updated macros against live content, and used on
pages that can let the macros fetch data from live content, without
actually deploying the macros to the production site. I expect this
to be one of the more interesting bits of the design process.
* As far as review cycles go, I'd sort of hoped to one day have a
proper review management interface on MDN that would be used for
both articles and macros; pulling the macros out means multiple
avenues to deal with for reviews. It's not a disaster or anything,
just a minor disappointment after years of wishful thinking. Don't
mind me. :)

I'm sure there's more but I'm not able to dig them up at the moment.
This is a good start.

--

Eric Shepherd
Senior Technical Writer
Mozilla <https://www.mozilla.org/>
Blog: http://www.bitstampede.com/
Twitter: http://twitter.com/sheppy
Check my Availability <https://freebusy.io/eshe...@mozilla.com>

[John Karahalis]

This sounds great. Having a documented, tested, and reviewed macro codebase
could be a very good thing. Sheppy raises important challenges. If we can
find solutions to those challenges (I think we can) I think we can make it
happen.

On Mon, Nov 2, 2015 at 11:57 AM, Florian Scholz <fsc...@mozilla.com> wrote:

> Hello MDN lists,

>
> this is a presentation for an idea that was brewing in the last couple
> weeks around a better system for how we work with macros. I collected some
> feedback from different people and presented this in the mdndev weekly
> planning meeting today.
>

> I would like to use this thread to further iterate on the idea, hash out
> more details, and come up with a plan or next steps, if we decide that want
> to do this.
>
>
> https://docs.google.com/presentation/d/1RE4qi047mFAwBChKMg-4CUSe23jFZmRDMbmCX867Bio/edit#slide=id.ge61d748be_2_37
>
> Sending to dev-mdc and dev-mdn as this involves governance questions and
> work for both teams (writers and kuma engineers).
>
> Also, we talked about a project called "macro cleanup" in the past. That
> cleanup is encompassed here.
>
> Looking forward to more thoughts!
> Florian
>
> --
> Florian Scholz
> Technical Writer
> Mozilla Developer Network
>

> _______________________________________________
> dev-mdn mailing list
> dev...@lists.mozilla.org
> https://lists.mozilla.org/listinfo/dev-mdn
>



--
John Karahalis
Mozilla
openjck.com

[Jean-Yves Perrier]

On 02/11/2015 17:51, Eric Shepherd wrote:
> * If we're on a fixed deployment schedule, what happens when we have
> to fix a bug that's critical, or if we have a project of content
> that depends on a macro deployment, which stalls out because of the
> deployment schedule. Having to time posting of articles to macro
> deployments is not something that's currently feasible; given that
> we do develop or update macros based on content changes, this will
> be a thing to deal with.

We are not speaking of a fixed deployment schedule. We are speaking of
using the same continuous deployment feature that the rest of the MDN
code base.

What happens when we have to fix a bug that's critical?
The same thing as a critical bug in the code base: this was a bit
problematic right after the Kuma migration but the devs have tightened
their processes and this working well now. No reason why this would be
different for code in macros

What happens when we have a project of content that needs a macro
deployment?
This is incredibly rare nowadays (wasn't in 2012), and yes most of these
projects are not blocked by a 2-3 days "delays" in macro reviewing,
unless we are very bad in planning it.

One exception: large week-end sprints.
But: usually devs are invited there too, and we will have a system to
test macros anyway… Having the actual macro/work live a few days later
will in fact be a good way to *reengage* contributors of the last sprint :-)

Nowadays we very rarely use new macros for content projects. I don't
remember one single example in 2015 where having a 2-3 day review
process would have been blocking a project. Surely not the quicklinks
macros or the new CSS macros, or the "add-a-standard-sentence" type of
macros that we have created here or there.

> * Before doing something like this, I'd like to better quantify what
> benefits we get on the platform side of things if we go this route,
> and what the specific challenges of making this change are.

Sure, the Kuma team has to make an analysis.

> * Macros in development very frequently are being developed or updated
> because of needs introduced by or oriented around recent content
> changes. This means that macros will have to be able to be tested
> against current site content. We'll need a way to test
> in-development or updated macros against live content, and used on
> pages that can let the macros fetch data from live content, without
> actually deploying the macros to the production site. I expect this
> to be one of the more interesting bits of the design process.

Test environment is an important element. We will not be able to launch
such feature without being able to test (seriously) PRs.

> * As far as review cycles go, I'd sort of hoped to one day have a
> proper review management interface on MDN that would be used for
> both articles and macros; pulling the macros out means multiple
> avenues to deal with for reviews. It's not a disaster or anything,
> just a minor disappointment after years of wishful thinking. Don't
> mind me. :)

I disagree: I think Github is enough here. Let's not over-engineer here
or play the "Not-invented here" syndrome: we surely don't want to
develop non-writing specific features when there are so many options out
there (or even inside Mozilla) that have resources allocated to
maintain. We surely don't want to implement a new code editing/reviewing
interface in MDN.


--
Jean-Yves Perrier
Senior St. Project Manager / Documentation Project / MDN

[Sebastian Zartner]

Personally I'd prefer an interface on MDN like Sheppy.
Though I'd also be fine to have a process on GitHub, I just fear that it
will become harder for contributors to write macros.

So how do you imagine the requirements for contributors (how can they test
the macros)? How does the process of contributing macros look like then?
And how will the process for porting existing macros to GitHub be like?

Sebastian

[Eric Shepherd]

Jean-Yves Perrier wrote:
> What happens when we have a project of content that needs a macro
> deployment?
> This is incredibly rare nowadays (wasn't in 2012), and yes most of
> these projects are not blocked by a 2-3 days "delays" in macro
> reviewing, unless we are very bad in planning it.

Hm... I still do this really often; pretty sure it's been just a few
weeks at most since that last one, although it might not be finished yet
due to ongoing goal-panic. :)

[Eric Shepherd]

Sebastian Zartner wrote:
> Personally I'd prefer an interface on MDN like Sheppy.
> Though I'd also be fine to have a process on GitHub, I just fear that it
> will become harder for contributors to write macros.

Yeah, but that's not the main reason for me. The main reason is that
having to do reviews in multiple places dilutes our work. Every context
switch is a break in activity and requires a mental shift to get back
into gear again. I don't like how we have to move all over the place to
get stuff done (even having some stuff in the admin panel and some stuff
done using buttons on the Kuma site itself is a distraction IMHO).
Please don't get me wrong! I get that we have to make choices, and we
have to prioritize, and if having the admin and tools be less convenient
lets us do more for the user, that's great. But we sometimes let that
seep into regular contributor tools, and that's less okay, since they're
users too.

That's not "not invented here." Not at all. It's "convenience breeds
efficiency." I believe pretty strongly in that. The easier something is
to use, the more you get done, and the better the results (assuming you
don't forgo too much capability in the process, but if anyone honestly
thinks I'd advocate for that, that just makes me sad).

I of course also don't advocate trying to do everything at once. But I
still feel that if your end goal isn't "awesome," why bother? :)

[Jean-Yves Perrier]

On 08/11/2015 22:35, Eric Shepherd wrote:
> Jean-Yves Perrier wrote:
>> What happens when we have a project of content that needs a macro
>> deployment?
>> This is incredibly rare nowadays (wasn't in 2012), and yes most of
>> these projects are not blocked by a 2-3 days "delays" in macro
>> reviewing, unless we are very bad in planning it.
> Hm... I still do this really often; pretty sure it's been just a few
> weeks at most since that last one, although it might not be finished
> yet due to ongoing goal-panic. :)
>

If it was possible to wait for weeks without finishing it, it is
therefore possible to wait a couple of days for a review.

[Sebastian Zartner]

On 8 November 2015 at 23:42, Eric Shepherd <eshe...@mozilla.com> wrote:

> Sebastian Zartner wrote:
>
> Personally I'd prefer an interface on MDN like Sheppy.
> Though I'd also be fine to have a process on GitHub, I just fear that it
> will become harder for contributors to write macros.
>
> Yeah, but that's not the main reason for me. The main reason is that
> having to do reviews in multiple places dilutes our work. Every context
> switch is a break in activity and requires a mental shift to get back into
> gear again.
>

And I also agree with that. Having to switch between tools is a burden. It
isn't my main reason, though, because a badly optimized process of editing
the macros weighs havier in my eyes than having to switch contexts.

Sebastian

[Sphinx]

Hello all,

As always, this message will be about l10n.
I am a proponent of this (especially regarding l10n macros). Having
content on GitHub makes it easier to fiddle with/experiment on.

Though I'm used to add strings in mdn.localString and to complete the
L10n:CSS template. I don't think that JSON is a very "respectable"
format for localization. I don't think either that many of us plan to
switch from JSON to some other format during the next weeks/months :)

Having the data on GitHub would make experimentation easier. in the end,
if the format is l10n-able (gettext, l10n.js, L20n, lang, etc.), it
could even feed Pontoon or whatever l10n tools you would use (thus
enlarging the potential audience of localizers \o/).

Again, these are not short term plans but getting there one step at a
time will offer more flexibility on GitHub (or on <insert your favorite
git web tool here>), especially for l10n where JSON might not always be
the right tool.

Mes deux centimes ;)
Respectfully,
Julien