1
00:00:02,779 --> 00:00:05,895
Hey there this is Mark, founder of modmore

2
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

3
00:00:11,469 --> 00:00:13,529
First things first, this is the documentation

4
00:00:13,529 --> 00:00:14,465
I'm referring to

5
00:00:14,844 --> 00:00:17,165
which is currently available on docs.modx.org

6
00:00:17,955 --> 00:00:21,659
which is different from the version that
runs on docs.modx.com

7
00:00:22,620 --> 00:00:26,631
it's basically a community project we've
been working on

8
00:00:26,631 --> 00:00:29,710
to convert the documentation to the
markdown format

9
00:00:29,710 --> 00:00:33,611
and hosting those on github to allow
open and transparent collaboration

10
00:00:33,611 --> 00:00:35,554
to make it better

11
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

12
00:00:41,075 --> 00:00:43,271
in the design or overall structure

13
00:00:43,271 --> 00:00:46,280
but this is basically what we're looking
at today

14
00:00:48,063 --> 00:00:52,239
so let's see how this works, how we can
make a change to this documentation

15
00:00:52,524 --> 00:00:55,740
let's say we were browsing the extras

16
00:00:55,740 --> 00:00:59,061
and we were looking at the
addHeaderfiles snippet

17
00:01:00,088 --> 00:01:03,835
and we noticed that this table here
doesn't look right

18
00:01:04,595 --> 00:01:08,031
the first column is missing, it seems to
have shifted

19
00:01:08,031 --> 00:01:11,266
and this is actually a result of the
conversion which happened

20
00:01:11,266 --> 00:01:14,852
on some pages which we can
quite easily fix

21
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

22
00:01:23,636 --> 00:01:27,447
and this will open a new page on github

23
00:01:29,115 --> 00:01:33,763
You do need a github account, which is
free if you don't already have one

24
00:01:33,763 --> 00:01:37,574
and I'll just login as my test account

25
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

26
00:01:44,188 --> 00:01:48,081
So the first thing it asks me for is to
fork the repository.

27
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.

28
00:01:52,472 --> 00:01:57,760
Just click the green button which
will basically make a copy of the

29
00:01:57,760 --> 00:02:00,583
official documentation that you can make
changes to directly.

30
00:02:01,937 --> 00:02:07,397
The official version, which is under the
modxorg name, not everyone can change

31
00:02:07,397 --> 00:02:11,852
that directly, so forking is the way to
start making changes.

32
00:02:12,671 --> 00:02:14,568
So I'll fork it.

33
00:02:15,273 --> 00:02:17,890
Which will land us in the edit view.

34
00:02:18,764 --> 00:02:24,966
It immediately sends us to the right page,
the addHeaderfiles extra.

35
00:02:25,715 --> 00:02:29,758
We can now look at what happened with
that table.

36
00:02:30,052 --> 00:02:34,249
So this is roughly how a table is managed
in markdown.

37
00:02:34,820 --> 00:02:36,574
There are these pipe symbols (|)

38
00:02:36,574 --> 00:02:39,054
and then there's content in the cell

39
00:02:39,054 --> 00:02:40,878
another pipe symbol, more content

40
00:02:42,628 --> 00:02:45,872
this is basically the separation between
the header and the body of a table

41
00:02:46,886 --> 00:02:48,123
and then there's the rest

42
00:02:49,473 --> 00:02:52,935
so the problem here is actually,
may be a bit hard to see

43
00:02:52,935 --> 00:02:56,384
but there's a space before each line
of the table

44
00:02:56,698 --> 00:02:58,517
that's causing it to not get rendered
properly

45
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

46
00:03:04,155 --> 00:03:07,544
which puts everything nicely in the
right place

47
00:03:09,080 --> 00:03:11,566
and while we're at it, we could also make
other changes

48
00:03:11,566 --> 00:03:14,359
I mean we could check the content, is it
written properly?

49
00:03:14,359 --> 00:03:17,200
maybe there are some formatting issues?

50
00:03:17,932 --> 00:03:22,685
I guess there's some code here that should
be wrapped in these little quotes

51
00:03:22,979 --> 00:03:26,289
to make sure they're formatted as code
as well

52
00:03:26,714 --> 00:03:30,980
so basically you can edit the entire page
content just from this view

53
00:03:32,938 --> 00:03:35,938
When you're happy with this, you need to
save the changes.

54
00:03:35,938 --> 00:03:38,305
That's called a "commit" in git terms.

55
00:03:38,305 --> 00:03:42,288
But you can do that just from the bottom
here where it says "Propose file change"

56
00:03:42,815 --> 00:03:50,820
So we can say "fix formatting issues on
addHeaderFiles page"

57
00:03:52,100 --> 00:03:54,765
You can add an additional description here
but that's not necessary

58
00:03:55,219 --> 00:03:58,089
We'll click the green button to propose
the file change

59
00:04:00,937 --> 00:04:05,335
That sends us into a view where we can
compare the changes we made

60
00:04:05,335 --> 00:04:06,964
to the official version.

61
00:04:07,983 --> 00:04:14,044
So we can see here the base repository
is Docs under modxorg, and ours is

62
00:04:14,044 --> 00:04:18,195
Mark-H2 with a certain branch name

63
00:04:19,520 --> 00:04:23,653
So we can see what we did, removed some
spaces and added some formatting

64
00:04:23,653 --> 00:04:24,857
at the bottom

65
00:04:28,705 --> 00:04:31,576
Now the next step is to click "Create Pull
Request"

66
00:04:32,556 --> 00:04:35,537
So as we are working in our own fork,
in our own copy

67
00:04:35,537 --> 00:04:40,582
the pull request is basically where you
ask maintainers of the official version

68
00:04:40,582 --> 00:04:46,403
like "this is the change I made, can you
please include it in the official version"

69
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

70
00:04:54,402 --> 00:04:58,458
basically the information needed by the
maintainers to see if it's a good change

71
00:04:58,458 --> 00:04:59,251
or not

72
00:05:00,141 --> 00:05:03,322
So we can describe this as

73
00:05:05,260 --> 00:05:12,919
"Some formatting issues on addHeaderFIles
Page causing table to not render properly"

74
00:05:17,604 --> 00:05:20,563
which affects version 2.x

75
00:05:20,903 --> 00:05:24,992
cause we do have different versions in
the documentation now

76
00:05:26,366 --> 00:05:29,820
and we don't have a relevant issue 
for this one

77
00:05:32,024 --> 00:05:34,041
So this is basically what we need
to fill out

78
00:05:35,665 --> 00:05:41,187
At this point the maintainers of the 
project get a notification

79
00:05:41,187 --> 00:05:43,871
that there's a new change

80
00:05:44,378 --> 00:05:47,190
I can actually show you what that
looks like

81
00:05:47,698 --> 00:05:50,551
when I'm bringing my other screen

82
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

83
00:05:58,183 --> 00:06:01,668
and I can see that Mark-H2, who is a
first-time contributor

84
00:06:01,668 --> 00:06:04,826
has suggested some changes

85
00:06:05,365 --> 00:06:07,521
I can review them through the files tab

86
00:06:08,848 --> 00:06:12,743
and when I say "okay this is a good
change, something we really need"

87
00:06:12,743 --> 00:06:16,016
I can merge it from here.

88
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

89
00:06:23,401 --> 00:06:27,606
What happens next is that the change needs
to be deployed which is semi-automatic

90
00:06:27,606 --> 00:06:29,728
it will be fully automatic soon

91
00:06:30,554 --> 00:06:33,730
So it looks like it's completed (the deployment)

92
00:06:35,902 --> 00:06:39,114
so now I can go back to my
documentation

93
00:06:39,900 --> 00:06:42,120
and if I refresh the page

94
00:06:43,547 --> 00:06:47,900
you will see that it is now a little
bit better

95
00:06:48,174 --> 00:06:51,037
there are still some formatting issues
here where it's breaking up the line

96
00:06:51,037 --> 00:06:54,351
but that's a design thing that needs to
be addressed differently

97
00:06:55,233 --> 00:06:59,331
you can see that the other change we made
here, properly marking these as code

98
00:06:59,806 --> 00:07:01,803
did apply properly

99
00:07:05,115 --> 00:07:08,749
So that's basically the process for
editing the documentation.

100
00:07:09,693 --> 00:07:14,530
You can go to anywhere on this website
to find the edit page link

101
00:07:14,573 --> 00:07:17,172
to get directly to the right page
on GitHub

102
00:07:18,144 --> 00:07:21,717
If you go to Github you can also browse
the documentation from there

103
00:07:22,227 --> 00:07:25,711
You can see we currently have English,
Dutch and Russian versions

104
00:07:26,646 --> 00:07:28,941
English is the source version

105
00:07:28,941 --> 00:07:32,450
the others are translations, and
especially Russian is coming along nicely

106
00:07:34,364 --> 00:07:39,074
We can just browse around here and say
okay maybe I want to change something

107
00:07:39,074 --> 00:07:42,488
in... I don't know.. the api reference

108
00:07:43,264 --> 00:07:45,096
which is not a very interesting page

109
00:07:46,333 --> 00:07:49,232
but then there's the edit link right here
at the top

110
00:07:49,903 --> 00:07:52,866
that will again bring us to the same
page we saw before

111
00:07:52,871 --> 00:07:56,672
where we can edit the page, edit the
source of the page, and propose

112
00:07:56,672 --> 00:07:59,640
the change at the bottom which will
send us into the pull request

113
00:07:59,640 --> 00:08:02,866
for the process of getting it merged
into the official version

114
00:08:04,141 --> 00:08:08,312
I do want to encourage everybody to
just see if you can help out with this

115
00:08:08,898 --> 00:08:12,964
there are a couple of issues logged
on github as well

116
00:08:12,964 --> 00:08:15,955
with things that have been identified
as needing to be fixed

117
00:08:16,751 --> 00:08:18,247
Thanks for watching

118
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

119
00:08:22,660 --> 00:08:26,235
without needing to know all about how
git works

120
00:08:26,235 --> 00:08:30,758
just the basics of changing a file and 
submitting it to be included