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