Hey there this is Mark, founder of modmore
and in this video I'm going to quickly show how you can help with editing the new MODX documentation
First things first, this is the documentation
I'm referring to
which is currently available on docs.modx.org
which is different from the version that
runs on docs.modx.com
it's basically a community project we've
been working on
to convert the documentation to the
markdown format
and hosting those on github to allow
open and transparent collaboration
to make it better
it's still under active development, so
if you watch this later you may notice
some things have changed
in the design or overall structure
but this is basically what we're looking
at today
so let's see how this works, how we can
make a change to this documentation
let's say we were browsing the extras
and we were looking at the
addHeaderfiles snippet
and we noticed that this table here
doesn't look right
the first column is missing, it seems to
have shifted
and this is actually a result of the
conversion which happened
on some pages which we can
quite easily fix
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
and this will open a new page on github
You do need a github account, which is
free if you don't already have one
and I'll just login as my test account
just so it's the same way it will be for
you the first time you edit something
So the first thing it asks me for is to
fork the repository.
If you're not familiar with how git or git
flow and all that works, no worries.
Just click the green button which
will basically make a copy of the
official documentation that you can make
changes to directly.
The official version, which is under the
modxorg name, not everyone can change
that directly, so forking is the way to
start making changes.
So I'll fork it.
Which will land us in the edit view.
It immediately sends us to the right page,
the addHeaderfiles extra.
We can now look at what happened with
that table.
So this is roughly how a table is managed
in markdown.
There are these pipe symbols (|)
and then there's content in the cell
another pipe symbol, more content
this is basically the separation between
the header and the body of a table
and then there's the rest
so the problem here is actually,
may be a bit hard to see
but there's a space before each line
of the table
that's causing it to not get rendered
properly
so what i'll do is, I'll just select
all the lines and do a shift-tab
which puts everything nicely in the
right place
and while we're at it, we could also make
other changes
I mean we could check the content, is it
written properly?
maybe there are some formatting issues?
I guess there's some code here that should
be wrapped in these little quotes
to make sure they're formatted as code
as well
so basically you can edit the entire page
content just from this view
When you're happy with this, you need to
save the changes.
That's called a "commit" in git terms.
But you can do that just from the bottom
here where it says "Propose file change"
So we can say "fix formatting issues on
addHeaderFiles page"
You can add an additional description here
but that's not necessary
We'll click the green button to propose
the file change
That sends us into a view where we can
compare the changes we made
to the official version.
So we can see here the base repository
is Docs under modxorg, and ours is
Mark-H2 with a certain branch name
So we can see what we did, removed some
spaces and added some formatting
at the bottom
Now the next step is to click "Create Pull
Request"
So as we are working in our own fork,
in our own copy
the pull request is basically where you
ask maintainers of the official version
like "this is the change I made, can you
please include it in the official version"
So we can just click that button which
will give us a new form to fill out
basically the information needed by the
maintainers to see if it's a good change
or not
So we can describe this as
"Some formatting issues on addHeaderFIles
Page causing table to not render properly"
which affects version 2.x
cause we do have different versions in
the documentation now
and we don't have a relevant issue
for this one
So this is basically what we need
to fill out
At this point the maintainers of the
project get a notification
that there's a new change
I can actually show you what that
looks like
when I'm bringing my other screen
So this is the same repository except now
I'm logged in as my main user account
and I can see that Mark-H2, who is a
first-time contributor
has suggested some changes
I can review them through the files tab
and when I say "okay this is a good
change, something we really need"
I can merge it from here.
So I'll confirm that and at this point the
change is made in the official version
What happens next is that the change needs
to be deployed which is semi-automatic
it will be fully automatic soon
So it looks like it's completed (the deployment)
so now I can go back to my
documentation
and if I refresh the page
you will see that it is now a little
bit better
there are still some formatting issues
here where it's breaking up the line
but that's a design thing that needs to
be addressed differently
you can see that the other change we made
here, properly marking these as code
did apply properly
So that's basically the process for
editing the documentation.
You can go to anywhere on this website
to find the edit page link
to get directly to the right page
on GitHub
If you go to Github you can also browse
the documentation from there
You can see we currently have English,
Dutch and Russian versions
English is the source version
the others are translations, and
especially Russian is coming along nicely
We can just browse around here and say
okay maybe I want to change something
in... I don't know.. the api reference
which is not a very interesting page
but then there's the edit link right here
at the top
that will again bring us to the same
page we saw before
where we can edit the page, edit the
source of the page, and propose
the change at the bottom which will
send us into the pull request
for the process of getting it merged
into the official version
I do want to encourage everybody to
just see if you can help out with this
there are a couple of issues logged
on github as well
with things that have been identified
as needing to be fixed
Thanks for watching
I hope this shows how you can help out,
how you can contribute to the new docs
without needing to know all about how
git works
just the basics of changing a file and
submitting it to be included