I have to say, this is a huge step forward for the docs (using Github + Markdown for actual proper VC of the text? Game changer positive for us.) And it’s pretty typical these days for software to either use Github for their documentation, or something like readme.io / Confluence. So the negative tone on this is … I don’t know, it feels really off to me, these are normal terms to be using for this kind of thing.
1 Like
Very nice job on the Extras list and the page. My only suggestions would be:
SPForm under forms. SPForm is particularly good for beginners because it essentially creates an instant, spam-proof contact form that works out of the box. Kind of the opposite of FormIt. 
MyComponent under Development Tools (or distributing your own extra).
NewsPublisher, UpgradeMODX, SiteCheck, and GoRevo are also fairly popular, but I’m not sure where they would go or if they should make the cut.
So I ended up doing a quick demonstration screencast of how editing the documentation works without using any git; just the browser and GitHub:
(I added subtitles cause I can sometimes speak a bit unclear; translations are welcome too.)
4 Likes
The new docs system is absolutely brilliant. It’s going to be so much easier keeping everything up to date now. I’ll jump in and make some edits soon.
Congrats to everyone involved!
2 Likes
A new design is ready for testing, with special thanks to @christianseel. Check it out: https://docs.modx.org/current/en/index
6 Likes
I’m not sure what you’re suggesting here? Where are these folks coming from? If they are a part of the MODX Community there is nothing to stop them from contributing and I know for a fact technical writers and documentation writers know how to use version control in 2019. We’re not going to have random members of the public magically volunteer their time to help out the documentation of a slightly obscure open source CMS. Also, I’m unsure of what a professional communications advisor is, but it doesn’t sound like it is the right choice here. Documentation and instructional writing are very very different than other forms of writing.
But, there are enough people here with varied backgrounds in the MODX Community to improve the documentation through a combination of developing/using a style guide and soliciting user feedback to help improve each document and the overall organization of the docs. Many people in the MODX Community have experience in writing books, web content, documentation for clients, marketing and more.
As @markh pointed out, if even 50 people put in a bit of time to improve some pages, even just a little bit, the documentation would see significant improvement over time.
As a living document, it will always be able to see improvement.
1 Like
I just deployed a first version of the search 
Try it: https://docs.modx.org/current/en/search
I’m especially interested in feedback on how well (or not) it’s finding what you’re looking for, so try finding things you’d normally search for, and let me know if the results are what you expect.
It’s a custom built search/indexer which uses fuzzy matching and a scoring system.
The numbers you see in each result (e.g “37 = 92/100”) reflect the score; a score of 40 (100/100) or higher is considered a confident result, a good match. Scores are assigned per matching word. Right now, a match in the page title is 10 points, matches in the other headers are 4 points (limited to 20 points for 5 occurrences in all headings), and body content is 1 point (limited to 20 points for 20 occurrences). I’ll probably play with these numbers a bit still though.
At the moment, only English docs for 2.x are indexed, so no results for 3.x or Russian/Dutch is expected (coming soon!). Some other things I’ll be working on include showing an extract of the result page, pagination, reindexing changed documentation, perhaps some more control over the fuzzy matching, and the code needs cleaning up and restructuring to make it easier to extend down the road.
3 Likes
Well done, Mark. Works well!
From a UX standpoint, a brief description/extract of the results might be more useful than the score. I would even drop the score altogether. But If you must keep it, you should reduce its font-size and use a muted gray color.
Also, the search doesn’t return the If extra, probably due to the minimum character number being higher than 2, which is understandable.
And, the search finds 623 results for the term MODX, but not all are returned.
I’ll post more as I find them.
Thanks for trying it 
It looks like “If” isn’t indexed because it’s a stopword; i.e. too commonly used in sentences that it’s filtered out as not having any real meaning. Like “a” and “the”. It does show up when searching for “condition”. Maybe I’ll take “if” out of the stopword list as that does have some real meaning for us…
It definitely isn’t done yet; like I mentioned showing an extract and adding pagination to see more than 10 results is still on the to do list.
Totally missed the to do list part. If not being indexed makes sense.
Another update for the search is now running on the site, e.g.: https://docs.modx.org/current/en/search?q=friendly+urls
Changes:
- It looks better now!
- Shows an extract of the page. Currently the start of the page body; might change it to get the relevant portion of the page instead later.
- Shows breadcrumbs leading to a page for a bit of very useful context (e.g. search for “roadmap”)
- Pagination added, so you can see beyond the first 10 results.
- The search now uses 100% of the weight on exact matches, and 75% for fuzzy matches (e.g. searching for
friendly urlswill use 100% of the weight forurls, but 75% of the weight forurl). - It’s now possible to quote individual words to force it to only use the exact match, e.g.
friendly "urls". The search page will also tell you that’s possible when fuzzy matches are used. - The score is shown more subtly now, but can also be clicked to get a bit more insight into why a certain page has a certain score.
- If words are ignored because they’re too short or a stopword, it will now tell you. (e.g. search for “if” or “what is a modx”)
Still more to be done but it should be a lot more user friendly with this update
6 Likes
This is a vast improvement. Well done!
2 Likes
Excellent updates.
1 Like
The awesome @lkfranklin has been working on updated/new docs explaining how to integrate templates: https://docs.modx.org/current/en/building-sites/integrating-templates
1 Like
I’ve updated the searching algorithm to also match on terms that you’re starting to type (e.g. synt will “autocomplete” to syntax). That’s not a fuzzy search (e.g. gertes wont figure out you’re typing getresources) but does help with another new search feature… live results as you type:
Search does need some work on mobile, so that’s next.
5 Likes
Exciting milestone - the legacy docs have now been replaced with this new system and content on docs.modx.com! That’s now on hardware sponsored by MODX LLC.
I’ll keep docs.modx.org running as a mirror (and probably rename it to docs-mirror.modx.org with a note at the top or such providing a link to the official version). The canonical is already updated, so search results should update automatically as well.
3 Likes
Looks beautiful. 
BTW, I’ve been trying to add UpgradeMODX for some time with no luck. I’m hoping I can do it at the new site once I have access.
Who needs access? You can send a pull request to add a new directory in https://github.com/modxorg/Docs/tree/2.x/en/extras
Some information on file naming and structures and such can be found here: https://docs.modx.com/current/en/contribute/documentation
1 Like
Thanks! I’ll give that a try.
1 Like
By popular request, there’s now an improved language/version switcher in the top right (top left on mobile). Based on initial work a while ago by @christianseel, which I’ve tried to not mess up too much.
The options point to the current page in the other language if available (that used to be right below the documentation title before), or if that page was not translated (like for Dutch in this example) it points to the index of that translation instead.
4 Likes