WEBVTT

00:00:02.779 --> 00:00:05.895
Hey there this is Mark, founder of modmore

00:00:05.895 --> 00:00:10.357
and in this video I'm going to quickly show how you can help with editing the new MODX documentation

00:00:11.469 --> 00:00:13.529
First things first, this is the documentation

00:00:13.529 --> 00:00:14.465
I'm referring to

00:00:14.844 --> 00:00:17.165
which is currently available on docs.modx.org

00:00:17.955 --> 00:00:21.659
which is different from the version that
runs on docs.modx.com

00:00:22.620 --> 00:00:26.631
it's basically a community project we've
been working on

00:00:26.631 --> 00:00:29.710
to convert the documentation to the
markdown format

00:00:29.710 --> 00:00:33.611
and hosting those on github to allow
open and transparent collaboration

00:00:33.611 --> 00:00:35.554
to make it better

00:00:36.294 --> 00:00:41.075
it's still under active development, so
if you watch this later you may notice
some things have changed

00:00:41.075 --> 00:00:43.271
in the design or overall structure

00:00:43.271 --> 00:00:46.280
but this is basically what we're looking
at today

00:00:48.063 --> 00:00:52.239
so let's see how this works, how we can
make a change to this documentation

00:00:52.524 --> 00:00:55.740
let's say we were browsing the extras

00:00:55.740 --> 00:00:59.061
and we were looking at the
addHeaderfiles snippet

00:01:00.088 --> 00:01:03.835
and we noticed that this table here
doesn't look right

00:01:04.595 --> 00:01:08.031
the first column is missing, it seems to
have shifted

00:01:08.031 --> 00:01:11.266
and this is actually a result of the
conversion which happened

00:01:11.266 --> 00:01:14.852
on some pages which we can
quite easily fix

00:01:16.146 --> 00:01:23.636
to do that we'll find the "Edit this page"
link which is located both here in the
title as well as in the footer

00:01:23.636 --> 00:01:27.447
and this will open a new page on github

00:01:29.115 --> 00:01:33.763
You do need a github account, which is
free if you don't already have one

00:01:33.763 --> 00:01:37.574
and I'll just login as my test account

00:01:37.574 --> 00:01:42.362
just so it's the same way it will be for
you the first time you edit something

00:01:44.188 --> 00:01:48.081
So the first thing it asks me for is to
fork the repository.

00:01:48.081 --> 00:01:52.472
If you're not familiar with how git or git
flow and all that works, no worries.

00:01:52.472 --> 00:01:57.760
Just click the green button which
will basically make a copy of the

00:01:57.760 --> 00:02:00.583
official documentation that you can make
changes to directly.

00:02:01.937 --> 00:02:07.397
The official version, which is under the
modxorg name, not everyone can change

00:02:07.397 --> 00:02:11.852
that directly, so forking is the way to
start making changes.

00:02:12.671 --> 00:02:14.568
So I'll fork it.

00:02:15.273 --> 00:02:17.890
Which will land us in the edit view.

00:02:18.764 --> 00:02:24.966
It immediately sends us to the right page,
the addHeaderfiles extra.

00:02:25.715 --> 00:02:29.758
We can now look at what happened with
that table.

00:02:30.052 --> 00:02:34.249
So this is roughly how a table is managed
in markdown.

00:02:34.820 --> 00:02:36.574
There are these pipe symbols (|)

00:02:36.574 --> 00:02:39.054
and then there's content in the cell

00:02:39.054 --> 00:02:40.878
another pipe symbol, more content

00:02:42.628 --> 00:02:45.872
this is basically the separation between
the header and the body of a table

00:02:46.886 --> 00:02:48.123
and then there's the rest

00:02:49.473 --> 00:02:52.935
so the problem here is actually,
may be a bit hard to see

00:02:52.935 --> 00:02:56.384
but there's a space before each line
of the table

00:02:56.698 --> 00:02:58.517
that's causing it to not get rendered
properly

00:02:59.073 --> 00:03:03.486
so what i'll do is, I'll just select
all the lines and do a shift-tab

00:03:04.155 --> 00:03:07.544
which puts everything nicely in the
right place

00:03:09.080 --> 00:03:11.566
and while we're at it, we could also make
other changes

00:03:11.566 --> 00:03:14.359
I mean we could check the content, is it
written properly?

00:03:14.359 --> 00:03:17.200
maybe there are some formatting issues?

00:03:17.932 --> 00:03:22.685
I guess there's some code here that should
be wrapped in these little quotes

00:03:22.979 --> 00:03:26.289
to make sure they're formatted as code
as well

00:03:26.714 --> 00:03:30.980
so basically you can edit the entire page
content just from this view

00:03:32.938 --> 00:03:35.938
When you're happy with this, you need to
save the changes.

00:03:35.938 --> 00:03:38.305
That's called a "commit" in git terms.

00:03:38.305 --> 00:03:42.288
But you can do that just from the bottom
here where it says "Propose file change"

00:03:42.815 --> 00:03:50.820
So we can say "fix formatting issues on
addHeaderFiles page"

00:03:52.100 --> 00:03:54.765
You can add an additional description here
but that's not necessary

00:03:55.219 --> 00:03:58.089
We'll click the green button to propose
the file change

00:04:00.937 --> 00:04:05.335
That sends us into a view where we can
compare the changes we made

00:04:05.335 --> 00:04:06.964
to the official version.

00:04:07.983 --> 00:04:14.044
So we can see here the base repository
is Docs under modxorg, and ours is

00:04:14.044 --> 00:04:18.195
Mark-H2 with a certain branch name

00:04:19.520 --> 00:04:23.653
So we can see what we did, removed some
spaces and added some formatting

00:04:23.653 --> 00:04:24.857
at the bottom

00:04:28.705 --> 00:04:31.576
Now the next step is to click "Create Pull
Request"

00:04:32.556 --> 00:04:35.537
So as we are working in our own fork,
in our own copy

00:04:35.537 --> 00:04:40.582
the pull request is basically where you
ask maintainers of the official version

00:04:40.582 --> 00:04:46.403
like "this is the change I made, can you
please include it in the official version"

00:04:47.267 --> 00:04:52.768
So we can just click that button which
will give us a new form to fill out

00:04:54.402 --> 00:04:58.458
basically the information needed by the
maintainers to see if it's a good change

00:04:58.458 --> 00:04:59.251
or not

00:05:00.141 --> 00:05:03.322
So we can describe this as

00:05:05.260 --> 00:05:12.919
"Some formatting issues on addHeaderFIles
Page causing table to not render properly"

00:05:17.604 --> 00:05:20.563
which affects version 2.x

00:05:20.903 --> 00:05:24.992
cause we do have different versions in
the documentation now

00:05:26.366 --> 00:05:29.820
and we don't have a relevant issue 
for this one

00:05:32.024 --> 00:05:34.041
So this is basically what we need
to fill out

00:05:35.665 --> 00:05:41.187
At this point the maintainers of the 
project get a notification

00:05:41.187 --> 00:05:43.871
that there's a new change

00:05:44.378 --> 00:05:47.190
I can actually show you what that
looks like

00:05:47.698 --> 00:05:50.551
when I'm bringing my other screen

00:05:53.176 --> 00:05:57.485
So this is the same repository except now 
I'm logged in as my main user account

00:05:58.183 --> 00:06:01.668
and I can see that Mark-H2, who is a
first-time contributor

00:06:01.668 --> 00:06:04.826
has suggested some changes

00:06:05.365 --> 00:06:07.521
I can review them through the files tab

00:06:08.848 --> 00:06:12.743
and when I say "okay this is a good
change, something we really need"

00:06:12.743 --> 00:06:16.016
I can merge it from here.

00:06:17.688 --> 00:06:22.770
So I'll confirm that and at this point the
change is made in the official version

00:06:23.401 --> 00:06:27.606
What happens next is that the change needs
to be deployed which is semi-automatic

00:06:27.606 --> 00:06:29.728
it will be fully automatic soon

00:06:30.554 --> 00:06:33.730
So it looks like it's completed (the deployment)

00:06:35.902 --> 00:06:39.114
so now I can go back to my
documentation

00:06:39.900 --> 00:06:42.120
and if I refresh the page

00:06:43.547 --> 00:06:47.900
you will see that it is now a little
bit better

00:06:48.174 --> 00:06:51.037
there are still some formatting issues
here where it's breaking up the line

00:06:51.037 --> 00:06:54.351
but that's a design thing that needs to
be addressed differently

00:06:55.233 --> 00:06:59.331
you can see that the other change we made
here, properly marking these as code

00:06:59.806 --> 00:07:01.803
did apply properly

00:07:05.115 --> 00:07:08.749
So that's basically the process for
editing the documentation.

00:07:09.693 --> 00:07:14.530
You can go to anywhere on this website
to find the edit page link

00:07:14.573 --> 00:07:17.172
to get directly to the right page
on GitHub

00:07:18.144 --> 00:07:21.717
If you go to Github you can also browse
the documentation from there

00:07:22.227 --> 00:07:25.711
You can see we currently have English,
Dutch and Russian versions

00:07:26.646 --> 00:07:28.941
English is the source version

00:07:28.941 --> 00:07:32.450
the others are translations, and
especially Russian is coming along nicely

00:07:34.364 --> 00:07:39.074
We can just browse around here and say
okay maybe I want to change something

00:07:39.074 --> 00:07:42.488
in... I don't know.. the api reference

00:07:43.264 --> 00:07:45.096
which is not a very interesting page

00:07:46.333 --> 00:07:49.232
but then there's the edit link right here
at the top

00:07:49.903 --> 00:07:52.866
that will again bring us to the same
page we saw before

00:07:52.871 --> 00:07:56.672
where we can edit the page, edit the
source of the page, and propose

00:07:56.672 --> 00:07:59.640
the change at the bottom which will
send us into the pull request

00:07:59.640 --> 00:08:02.866
for the process of getting it merged
into the official version

00:08:04.141 --> 00:08:08.312
I do want to encourage everybody to
just see if you can help out with this

00:08:08.898 --> 00:08:12.964
there are a couple of issues logged
on github as well

00:08:12.964 --> 00:08:15.955
with things that have been identified
as needing to be fixed

00:08:16.751 --> 00:08:18.247
Thanks for watching

00:08:18.247 --> 00:08:22.660
I hope this shows how you can help out,
how you can contribute to the new docs

00:08:22.660 --> 00:08:26.235
without needing to know all about how
git works

00:08:26.235 --> 00:08:30.758
just the basics of changing a file and 
submitting it to be included