Docs Meeting Logs July 23rd, 2015

irc.txt

[2015-07-23 11:01:07] <weaverryan> o/ WouterJ, xabbuh
[2015-07-23 11:01:16] <xabbuh> hi Ryan
[2015-07-23 11:01:27] <weaverryan> I just messaged Javier to see if he'll be available
[2015-07-23 11:01:34] <WouterJ> hi weaverryan
[2015-07-23 11:02:05] <weaverryan> WouterJ: you've been busy with link checking and docs bot ;)
[2015-07-23 11:02:08] <weaverryan> How was your holiday?
[2015-07-23 11:02:21] → javier_eguiluz joined (uid41340@gateway/web/irccloud.com/x-otwovigfahjblrep)
[2015-07-23 11:02:42] <javier_eguiluz> hi :)
[2015-07-23 11:02:48] <WouterJ> weaverryan, very relaxing :)
[2015-07-23 11:03:13] <WouterJ> and yeah, I wanted link checking for a long time already (but didn't knew there was a built-in builder for that)
[2015-07-23 11:03:17] <weaverryan> Javier! Glad you could make it too :)
[2015-07-23 11:03:44] <weaverryan> So, how about that new Symfony SE homepage? Everything will become a little controversial
[2015-07-23 11:04:17] <javier_eguiluz> most people seems to agree on being better than the current situation
[2015-07-23 11:04:19] <javier_eguiluz> so I'm happy
[2015-07-23 11:04:31] <WouterJ> if we keep it simple, I'm +1
[2015-07-23 11:04:58] <weaverryan> Agreed - and we'll never have 100% agreement on anything
[2015-07-23 11:05:11] <weaverryan> So, let's get started - I have a few topics in mind
[2015-07-23 11:05:13] <WouterJ> (I like Laravel's start page for instance, very simple)
[2015-07-23 11:05:21] <weaverryan> (thanks in part to Wouter)
[2015-07-23 11:05:47] <javier_eguiluz> @WouterJ can you link me a screenshot of that page please?
[2015-07-23 11:05:49] <weaverryan> Me too - and the new SE one is basically just as simple
[2015-07-23 11:05:58] <weaverryan> Javier - I emailed it to you in our email chain
[2015-07-23 11:06:23] <javier_eguiluz> @weaverryan yes, but I  wasn't sure if Wouter was referring to the same page
[2015-07-23 11:07:02] <weaverryan> I sent over the big Laravel 5 gray text on a white page thing. I assume that's what Wouter is talking about too
[2015-07-23 11:07:24] <javier_eguiluz> do you really find that page useful?
[2015-07-23 11:07:26] <WouterJ> yeah (but then for lumen)
[2015-07-23 11:07:42] <weaverryan> Lumen is different?
[2015-07-23 11:08:00] <weaverryan> Javier - not useful, but at least functional and striking
[2015-07-23 11:08:13] <weaverryan> Our's is more useful certainly
[2015-07-23 11:09:50] <weaverryan> Ok, let's get rolling: A) Symfony.com Platform.sh docs theme 
[2015-07-23 11:09:51] <WouterJ> let's start with the topics (I'll craft a Lumen application meanwhile)
[2015-07-23 11:10:21] <weaverryan> Javier - are the docs on symfony.com rendered with a custom Sphinx theme?
[2015-07-23 11:10:38] <weaverryan> Because I'm not worried about actually making it look like the symfony.com layout
[2015-07-23 11:10:44] <javier_eguiluz> I don't know what a "Sphinx theme" really is
[2015-07-23 11:10:49] <weaverryan> but the docs content itself is rendering with slightly different markup
[2015-07-23 11:10:56] <javier_eguiluz> but yes, we use a private repo which is almost the same as fabpot/sphinx
[2015-07-23 11:11:00] <javier_eguiluz> but with a few additions
[2015-07-23 11:11:21] <WouterJ> in the mail, you mentioned Twig
[2015-07-23 11:11:38] <WouterJ> so I assume the theme is more than Sphinx node visitors and CSS?
[2015-07-23 11:11:48] <weaverryan> Compare the markup of the first code blocks http://symfony.com/doc/current/book/controller.html and http://pr-5551-6qmocelev2lwe.eu.platform.sh/book/controller.html
[2015-07-23 11:12:05] <WouterJ> weaverryan, custom mark-up is added by visitors IIRC
[2015-07-23 11:12:37] <weaverryan> WouterJ: Did someone mention this in the past? I assume that's something in the private repo that does this?
[2015-07-23 11:12:56] <WouterJ> javier showed some snippets in a website issue
[2015-07-23 11:13:12] <javier_eguiluz> ok, there are two things
[2015-07-23 11:13:13] <javier_eguiluz> 1) sphinx
[2015-07-23 11:13:18] <javier_eguiluz> 2) twig + symfony app + CSS
[2015-07-23 11:13:35] <javier_eguiluz> I think we can easily solve 1)  and we can just use CSS from 2)
[2015-07-23 11:13:59] <javier_eguiluz> the only thing I see we could take from the private repo is one codeblock.py thing
[2015-07-23 11:14:06] <javier_eguiluz> which doesn't exist in fabpot/sphinx
[2015-07-23 11:14:17] <weaverryan> oooOOOooo
[2015-07-23 11:14:19] <javier_eguiluz> I will email it to you
[2015-07-23 11:14:35] <xabbuh> that would be great
[2015-07-23 11:14:57] <xabbuh> we could then also try to build it locally first
[2015-07-23 11:15:03] <xabbuh> and see how it looks like
[2015-07-23 11:15:15] <weaverryan> good idea - then make decisions from there
[2015-07-23 11:15:35] <weaverryan> Ok, end of topic then!
[2015-07-23 11:15:53] <weaverryan> B) Rewriting the quick tour
[2015-07-23 11:16:16] <weaverryan> WouterJ - quick description/history for us please?
[2015-07-23 11:17:11] <WouterJ> yes, of course
[2015-07-23 11:17:28] <WouterJ> the current Quick Tour is kind of still what was written as the first official Symfony documentation. It mostly uses the AcmeDemoBundle in the SE to explain the most basic things of Symfony.
[2015-07-23 11:17:35] <WouterJ> it was a real start point back then
[2015-07-23 11:17:59] <WouterJ> now, we have a Symfony Demo and the AcmeDemoBundle is removed. The Quick Tour isn't updated for this
[2015-07-23 11:18:29] <WouterJ> also, I think we start using the book articles (page creation) as start point and use Quick Tour more as an advertisement of Symfony
[2015-07-23 11:18:56] <weaverryan> I agree with this point - otherwise we sort of have 2 installation/get started sections
[2015-07-23 11:19:21] <WouterJ> almost all of us have already stated somewhere that we should rewrite it
[2015-07-23 11:19:44] <WouterJ> however, we never started... So I think it's good to create some sort of abstract for the new Quick Tour and start working on it
[2015-07-23 11:20:06] <javier_eguiluz> The most important thing is to clearly decide what is the Quick Tour
[2015-07-23 11:20:16] <javier_eguiluz> I wrongly thought it was "Teh Symfony tutorial"
[2015-07-23 11:20:16] ⇐ cfo quit (~cfo@HSI-KBW-46-223-12-228.hsi.kabel-badenwuerttemberg.de): Quit: cfo
[2015-07-23 11:20:25] <weaverryan> Question: should we expect someone to code along with the quick tour? Or are we just showing them things to get excited?
[2015-07-23 11:20:36] <javier_eguiluz> but Fabien told me that this should showcase the best features of Symfony (its compatitive advantages over other frameworks)
[2015-07-23 11:21:02] <javier_eguiluz> therefore, the contents shouldn't flow continuously ... you don't have to develop an entire application ... showing code snippets is enough
[2015-07-23 11:21:43] <weaverryan> And then we also don't need to cover installation
[2015-07-23 11:21:50] <WouterJ> I think using a reference, like the demo app, is a good idea. This way, you still have some flow and people always see how it works in the application
[2015-07-23 11:22:23] <javier_eguiluz> @W
[2015-07-23 11:22:33] <javier_eguiluz> @WouterJ but then you want to do a tutorial, not a quick tour
[2015-07-23 11:23:07] <weaverryan> I'd love to be showing the demo app too - but we can't really then show very simple, controlled examples (like that are there now) - those don't exist in the demo
[2015-07-23 11:23:42] <weaverryan> Certainly we can say "Want to skip ahead and play with a fully-featured demo Symfony app? ..."
[2015-07-23 11:24:44] <weaverryan> WouterJ: thoughts on that last point?
[2015-07-23 11:25:48] <WouterJ> I don't know the demo app good enough to really see if we can't show simple, controlled examples. I've used the CMF demo bundle for the CMF Quick Tour, picked some things from it and explained each level and I think it worked out pretty well (but I agree, it's maybe more a tutorial)
[2015-07-23 11:26:49] <WouterJ> also, I'm a bit unsure about "compatitive advantages over other frameworks".
[2015-07-23 11:27:21] <weaverryan> WouterJ What do you mean?
[2015-07-23 11:27:36] <WouterJ> like, how can you write a nice to read article (the current Quick Tour is very easy to read) about just some not related features?
[2015-07-23 11:28:06] <WouterJ> and also, what are the real compatitive advantages of frameworks in terms of code things?
[2015-07-23 11:28:08] <weaverryan> I think we write the quick your specifically by listing *exactly* what makes Symfony great, and using that as a guide
[2015-07-23 11:28:49] <weaverryan> And we should of course make it feel connected with a flow - like the Tour currently is
[2015-07-23 11:29:03] <javier_eguiluz> @WouterJ a similar concept would be the following: This is the "Quick Tour" of GitHub: https://github.com/features  and this is the tutorial of GitHub: https://help.github.com/
[2015-07-23 11:29:17] <weaverryan> There are slight differences, however, when you *really* expect someone to code along (like needing to cover all installation cases)
[2015-07-23 11:30:15] <WouterJ> thanks Javier, I know get a bit better what you want
[2015-07-23 11:31:04] <WouterJ> but that page also illustrates my point: There is no real flow (which they even emphasis with their styling)
[2015-07-23 11:32:09] <weaverryan> I envision the future quick tour looking a lot like the current quick tour: but updated to remove some details (like installation), some techy things that maybe aren't important (e.g. talking about front controllers) and adding more stuff that isn't there now (e.g. some API stuff)
[2015-07-23 11:32:10] <javier_eguiluz> @WouterJ exactly. In the case of the Quick Tour, not having a continuous flow is actually a great thing. You can forget about details and cumbersome things (installing, loading fixtures, removing this or that, etc.)
[2015-07-23 11:33:39] <weaverryan> Does anyone want to take a first attempt at updating this?
[2015-07-23 11:34:50] <WouterJ> I prefer not to
[2015-07-23 11:35:00] <xabbuh> I would want to, but I am pretty busy the next weeks :(
[2015-07-23 11:35:05] <javier_eguiluz> maybe it would be better if the "thinking part" is shared among all of us
[2015-07-23 11:35:11] <javier_eguiluz> we can outline th enew contents to write
[2015-07-23 11:36:18] <javier_eguiluz> I can work on the part of "doing it", but I need help in the other part where we think what do we exactly want to do
[2015-07-23 11:36:36] <weaverryan> That is a pre-requisite: getting a quick list of what features we'd highlight
[2015-07-23 11:36:41] <WouterJ> +1 for doing the outlining together first
[2015-07-23 11:37:30] <xabbuh> yeah, that's a must have, otherwise the person rewriting the tour would waste too much time
[2015-07-23 11:37:31] <weaverryan> I'll send out an email to get us started later
[2015-07-23 11:39:11] <weaverryan> Ok, sorry - got distracted for a second :)
[2015-07-23 11:39:38] <weaverryan> Before I put any more topics to the room, does anyone else have anything on their mind? Ideas? Things they've been dreaming about?
[2015-07-23 11:39:52] <javier_eguiluz> nope
[2015-07-23 11:40:13] <xabbuh> I would love to see the API links fixed :)
[2015-07-23 11:40:56] <javier_eguiluz> they should be fixed soon ... this time for real
[2015-07-23 11:41:06] <weaverryan> haha, indeed - we're all over-busy. I would love to see 5 more Javier's  - he's very useful ;)
[2015-07-23 11:41:24] <WouterJ> Little update: Docbot will receive another big rewrite. It currently is not syntax aware, which runs into many unsolvable problems. I'm planning to update it to extend PHP-CS-Fixer, so that it will be syntax aware (and provide patches with the fix!)
[2015-07-23 11:41:39] <weaverryan> WOW
[2015-07-23 11:41:41] <javier_eguiluz> awesome!
[2015-07-23 11:41:55] <weaverryan> that will be very interesting!
[2015-07-23 11:41:56] <WouterJ> also, I'm thinking about the usefullness of the docbot when used in Travis...
[2015-07-23 11:42:15] <weaverryan> meaning "should we fail if docbot has a problem"?
[2015-07-23 11:42:23] <WouterJ> currently, we almost always repeat the error shown in Travis in a comment.
[2015-07-23 11:42:33] <WouterJ> so I'm worrying it won't actually save much time for us
[2015-07-23 11:43:12] <xabbuh> well, if docbot catches things that could not be caught by the usual Sphinx build, that will actually be a great improvement
[2015-07-23 11:44:13] <weaverryan> So let's talk about that when we get ready - we can always try it and see if it works or drives us crazy
[2015-07-23 11:44:24] <xabbuh> maybe we could even have a look at the spellchecker again
[2015-07-23 11:44:31] <WouterJ> fine by me :)
[2015-07-23 11:44:41] <weaverryan> I think with platform.sh stuff and the quick tour, we've got a nice list of things to focus on for this month
[2015-07-23 11:44:59] <weaverryan> So, I don't want to bring anything else up - if we got that stuff done, that'd be awesome
[2015-07-23 11:45:13] <WouterJ> another thing that came in my mind yesterday: Can we change the response text of platform.sh in the github status bar?
[2015-07-23 11:45:45] <weaverryan> "Platform.sh: Environment deployed" ?
[2015-07-23 11:46:15] <WouterJ> without knowing anything about platform.sh or the things we recently set-up, I would not think about clicking on a link called "platformsh — Platform.sh: Environment deployed" for a preview
[2015-07-23 11:46:34] <WouterJ> especially since it's hidden under another "Show all checks" link
[2015-07-23 11:47:13] <weaverryan> That's probably more of a problem
[2015-07-23 11:47:40] <weaverryan> which could only be truly improved if something commented with the build link
[2015-07-23 11:47:57] <weaverryan> which would be cool - but I think we'd need to add something to do that
[2015-07-23 11:48:50] — WouterJ remembers the anoying Travis bot that commented with the build status some years ago
[2015-07-23 11:49:05] <weaverryan> haha, yes, re-creating old problems :)
[2015-07-23 11:49:18] <weaverryan> or it could update the PR description - but same problem, something needs to do that
[2015-07-23 11:49:27] <weaverryan> I'm not going to bring up any more topics today
[2015-07-23 11:49:48] <javier_eguiluz> I have one question
[2015-07-23 11:49:53] <weaverryan> In the future, we'll talk about C) fixing forms, doctrine, security - but I don't think anything will get done with that realistically right now
[2015-07-23 11:50:05] <xabbuh> that would mean that we needed a way to be notified when a service finishes
[2015-07-23 11:50:24] <javier_eguiluz> regarding the Platform.sh doc build
[2015-07-23 11:50:35] <javier_eguiluz> what if some of your robots
[2015-07-23 11:50:48] <javier_eguiluz> updates the description of the pull request when the doc build is ready
[2015-07-23 11:50:53] <javier_eguiluz> to add a quick link to it
[2015-07-23 11:51:06] <javier_eguiluz> something like "Preview the changes made in this PR in this link"
[2015-07-23 11:51:33] <weaverryan> haha, some of my robots? It's a good idea - someone just needs to do it. And I'm not 100% sure if we have a hook for when a service finishes or not (xabbuh's point) - we could research that
[2015-07-23 11:51:43] <weaverryan> I mean, i like it - it would be way more useful
[2015-07-23 11:51:52] <weaverryan> Javier : new SE homepage just got merged :)
[2015-07-23 11:52:00] <javier_eguiluz> great!
[2015-07-23 11:52:02] <WouterJ> o/
[2015-07-23 11:52:07] <WouterJ> great :)
[2015-07-23 11:52:19] <xabbuh> awesome :)
[2015-07-23 11:52:27] <WouterJ> now we can update all these URLs in the docs again (and my linkcheck won't catch them...)
[2015-07-23 11:52:53] <weaverryan> and update the screenshots
[2015-07-23 11:53:27] <weaverryan> A PR to do that should be ready, but not actually released until we have the next 2.7.* release - because that's when the SE (with the new homepage) will become available
[2015-07-23 11:53:44] <WouterJ> btw, what do you think about adding the linkcheck build to the Travis build? As explained in https://github.com/symfony/symfony-docs/pull/5553#issuecomment-123851808, I'm -1
[2015-07-23 11:53:58] <weaverryan> I agree with you - good reasons you gave
[2015-07-23 11:54:04] <xabbuh> not for pull requests
[2015-07-23 11:54:22] <xabbuh> we could just think about doing it for normal pushes, but I am not sure if it's worth it
[2015-07-23 11:54:22] <javier_eguiluz> @weaverryan this welcome page will be merged in 2.3, 2.6, 2.7, etc.  so whenever a new version is released, people will see it.
[2015-07-23 11:55:09] <weaverryan> Javeri: exactly - but the next 2.3 release may not be the same time as the next 2.7 release (ideally they're close). Since most new projects use 2.7, the best we can do is merge that PR when the 2.7 release becomes available, right?
[2015-07-23 11:55:36] <weaverryan> I say "meh" about the link checker automatically - we can run it occasionally
[2015-07-23 11:55:40] <weaverryan> Javier*
[2015-07-23 11:55:59] <javier_eguiluz> @weaverryan I understand. You are right, yes.
[2015-07-23 11:56:02] <WouterJ> okay, exactly my opinion. So let's not add it for now
[2015-07-23 11:56:57] <weaverryan> Ok, I gotta run. Let's kill it on our 2 items and see if we can keep getting those PR's lower and lower
[2015-07-23 11:56:57] <WouterJ> javier_eguiluz, did you get message about 2.8 not being available as version on symfony.com?

(17:58:27)<weaverryan>Next meeting Thu Aug 20th?
(17:59:02)<javier_eguiluz>ok
(17:59:03)<WouterJ>I'm probably not available at 5 PM in Aug
(17:59:24)<WouterJ>so I would prefer 2 hours later (or being of September)
(17:59:29)<WouterJ>s/being/begin
(17:59:43)<xabbuh>two ours later would be better for me too
(17:59:48)<xabbuh>hours
(18:00:01)<weaverryan>2 hours later is ok for me
(18:00:08)<javier_eguiluz>ok for me too