WEBVTT NOTE Created by CaptionSync from Automatic Sync Technologies www.automaticsync.com 00:00:00.066 --> 00:00:04.616 align:middle After waiting about a minute, oh! 00:00:05.156 --> 00:00:10.196 align:middle You'll notice that the continuous integration for our documentation pull request failed? 00:00:10.756 --> 00:00:12.436 align:middle What does that even mean? 00:00:12.896 --> 00:00:14.436 align:middle Are there tests for the docs? 00:00:15.666 --> 00:00:17.926 align:middle Let's learn a few important things about the docs. 00:00:17.926 --> 00:00:23.956 align:middle First, you probably noticed that all the files use a .rst extension. 00:00:24.476 --> 00:00:26.736 align:middle That's called Restructured text. 00:00:28.006 --> 00:00:29.806 align:middle It's a lot like markdown... 00:00:30.186 --> 00:00:31.656 align:middle on steroids. 00:00:32.206 --> 00:00:36.536 align:middle It has, for example, a special syntax for linking from one page 00:00:36.536 --> 00:00:39.566 align:middle to another - that's this :doc: stuff. 00:00:39.566 --> 00:00:45.026 align:middle Behind the scenes, a build process turns all of this into HTML. 00:00:45.486 --> 00:00:51.026 align:middle But, if we have a link to a document that doesn't exist, that build will fail! 00:00:51.946 --> 00:00:53.866 align:middle Click "Details" to open Travis CI. 00:00:55.316 --> 00:00:58.556 align:middle The continuous integration system does exactly that: 00:00:59.116 --> 00:01:02.186 align:middle it runs the build to make sure all the basic stuff is okay: 00:01:02.746 --> 00:01:05.096 align:middle syntax, links and a few other things. 00:01:06.206 --> 00:01:07.256 align:middle And... yep! 00:01:07.756 --> 00:01:15.556 align:middle We have an error: apparently security.rst line 1269 contains a reference 00:01:15.656 --> 00:01:20.346 align:middle to a non-existent document security/target_path. 00:01:21.246 --> 00:01:23.356 align:middle That's the page we removed! 00:01:24.296 --> 00:01:28.506 align:middle Instead of printing a broken link, we know we need to remove it! 00:01:29.086 --> 00:01:37.056 align:middle Move back over, find the security.rst file and scroll down to line 1269. 00:01:38.676 --> 00:01:46.296 align:middle Ah. This toctree thing is another feature of RST - it helps build the table of contents. 00:01:47.656 --> 00:01:50.156 align:middle Remove the security/target_path line. 00:01:51.246 --> 00:01:55.536 align:middle To make sure there aren't any other references, find your terminal and search: 00:01:56.256 --> 00:02:02.156 align:middle git grep security/target_path Only one other spot - redirection_map. 00:02:02.946 --> 00:02:08.166 align:middle That's an internal tool to help us manage old URLs: not something we need to worry about. 00:02:09.036 --> 00:02:12.976 align:middle Let's commit: git add -ugit commit -- 00:02:12.976 --> 00:02:19.596 align:middle amend I'm using amend because this isn't an important change worth making a second commit. 00:02:20.586 --> 00:02:24.946 align:middle Push with: git push weaverryan remove-outdated-note -- 00:02:25.096 --> 00:02:28.766 align:middle force Hopefully the build will work this time. 00:02:29.926 --> 00:02:36.506 align:middle Ok: back to our original task: we need to write documentation for our new feature. 00:02:37.116 --> 00:02:42.766 align:middle That means we need to create a documentation PR against the master branch. 00:02:43.936 --> 00:02:46.126 align:middle Go back to to the terminal and create a new branch: 00:02:46.816 --> 00:02:54.686 align:middle git checkout -b target-path-helper origin/master Awesome! 00:02:55.276 --> 00:02:58.696 align:middle Move back and open the form_login.rst file again. 00:02:59.576 --> 00:03:01.956 align:middle Scroll all the way down to the bottom. 00:03:04.176 --> 00:03:09.606 align:middle If you're not comfortable writing documentation or if you're a non-native English speaker, 00:03:10.016 --> 00:03:12.916 align:middle you might think that writing docs isn't for you. 00:03:13.786 --> 00:03:16.286 align:middle That's totally not true! 00:03:17.006 --> 00:03:22.116 align:middle The really important thing about writing docs is creating good code examples. 00:03:22.466 --> 00:03:27.696 align:middle Pay less attention to writing words and more attention to writing code 00:03:28.066 --> 00:03:30.176 align:middle that shows how your feature is used. 00:03:31.186 --> 00:03:36.136 align:middle When you submit your PR, the docs team can help reword & improve the little details. 00:03:36.516 --> 00:03:39.096 align:middle The hard work is writing the code. 00:03:40.236 --> 00:03:45.006 align:middle I'll start with a quick sentence, then right into the code block. 00:03:49.236 --> 00:03:51.666 align:middle I'll paste in an example I already created. 00:03:52.626 --> 00:03:55.546 align:middle And, yeah, this green background is super annoying: 00:03:55.576 --> 00:03:58.356 align:middle I don't normally use PhpStorm for documentation. 00:03:59.686 --> 00:04:02.386 align:middle Anyways, a few important things about the format. 00:04:02.386 --> 00:04:08.916 align:middle First, any technical term - like a class name - should be surrounded by two ticks. 00:04:10.686 --> 00:04:16.106 align:middle Second, when you want to add a PHP code block, finish the previous sentence 00:04:16.106 --> 00:04:18.356 align:middle with two colons and indent the code. 00:04:19.616 --> 00:04:24.496 align:middle And third, when you're inside the code, put as much context as possible. 00:04:24.496 --> 00:04:30.196 align:middle For example, I've added a note to say that this code is from a controller. 00:04:31.576 --> 00:04:36.926 align:middle You should also be sure to include any use statements needed for the new code. 00:04:37.976 --> 00:04:41.006 align:middle Well, we don't include use statements for everything. 00:04:41.606 --> 00:04:45.146 align:middle For example, I didn't include the use statement for the Request 00:04:45.516 --> 00:04:51.116 align:middle because people probably know what that is and it's not directly relevant to what we're doing. 00:04:51.966 --> 00:04:57.606 align:middle But, I did add the use statement for the class we're talking about: TargetPathHelper. 00:04:59.166 --> 00:05:04.556 align:middle Finally, we recommend avoiding big paragraphs of explanatory text. 00:05:05.176 --> 00:05:08.316 align:middle That's why we just included once sentence then code. 00:05:08.316 --> 00:05:14.316 align:middle If you want to explain a bit more, try adding comments into the code instead. 00:05:15.346 --> 00:05:19.616 align:middle We've found that people tend to read the code, but skip the paragraphs completely. 00:05:20.146 --> 00:05:21.496 align:middle Use that to your advantage! 00:05:22.576 --> 00:05:23.706 align:middle And... that's it! 00:05:24.566 --> 00:05:28.086 align:middle Sure, there are a lot of other little format details. 00:05:28.486 --> 00:05:33.556 align:middle But, the docs have plenty of examples of how to do just about anything. 00:05:34.466 --> 00:05:38.556 align:middle Oh, but because this is a new feature, I'll add one more thing. 00:05:39.216 --> 00:05:45.226 align:middle Right above the new text, add a special versionadded:: 4.2 tag. 00:05:46.286 --> 00:05:52.126 align:middle If our feature is merged, it will be included in Symfony 4.2 - the next Symfony version. 00:05:53.376 --> 00:05:57.136 align:middle This will add a new note highlighting this fact. 00:05:57.136 --> 00:05:59.576 align:middle This syntax is also special to RST. 00:05:59.576 --> 00:06:02.436 align:middle You can make tips and notes the same way. 00:06:03.816 --> 00:06:14.366 align:middle Ok - let's move over, add this file, and commit: And... 00:06:14.526 --> 00:06:22.416 align:middle push: git push weaverryan target-path-helper Move back over to GitHub. 00:06:25.536 --> 00:06:29.696 align:middle Hey! The tests passed on our other pull request! 00:06:29.926 --> 00:06:36.446 align:middle Sweet! And, just like always, if you don't see the yellow bar here, go back to your fork, 00:06:41.736 --> 00:06:45.626 align:middle select the new branch and hit "New pull request". 00:06:46.676 --> 00:06:50.636 align:middle This time, our pull request should be against the master branch. 00:06:51.916 --> 00:06:58.386 align:middle I'll prefix the title with [WCM] - that means "Waiting for Code Merge" - 00:06:59.416 --> 00:07:04.716 align:middle a little flag to help us know this is for a still-unmerged new feature. 00:07:04.786 --> 00:07:12.156 align:middle For the body, saying see symfony/symfony#28181 should be enough. 00:07:12.156 --> 00:07:14.336 align:middle Create that pull request! 00:07:18.176 --> 00:07:20.906 align:middle Hey! You're now a docs expert! 00:07:21.446 --> 00:07:24.686 align:middle So, I hope to see a bunch of docs PR's from you. 00:07:25.506 --> 00:07:26.036 align:middle Do it!