vimeo.com/.../330122657

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