jaygilmore
commented
8 years ago The reason we built them in MODX at the time was:
- MediaWiki was a security seive
- Github was for developers and coders and another closed system for non developers
- It seemed to make sense to build it in MODX since it was content and MODX is meant for managing content.
I now think GitHub is fine however, I don't think PRs will speed things up. I think they will slow things down. RTFM is essentially being used as a wiki with controlled access. If you get access (we give access to nearly every person that asks), you can make edits anytime you'd like. If this gets put into a GitHub project, who's going to manage PRs? For less technical folks or perhaps a developer who uses Mercurial or SVN for their VCS submitting git PRs is a potential hurdle.
I don't know what you mean by entirely open? RTFM access has been granted to almost every single person who has ever asked.
I should say, that for users, the do not wish to be trolling github for various and sundry extras documentation. They want to go to the single source. This has been asked over and over through the years. People do not want to hunt down other sites.
I'd suggest that the problems with the docs have to do with quality control and ongoing management and a lack of an author's guide. I could support a forkable version controlled version but I'd love to also have non technical editors be able to make changes without having to submit a PR. On the PR front, who's going to review and admit the PRs. Open Source projects need management.
Currently, people are free to make any and all changes they'd like, just by logging in. If PRs are needed, then someone's going to have to review and accept them. While the quality will possibly improve, I can't see how the frequency of change could overcome that management bottleneck.
Perhaps all the docs go to github but then there's the fragmentation issue. I'd still love them collated and output on a site together so people could go to docs.modx.com and find the info they are looking for. Taking people away from the modx.com domain can be a small trust breaker for those less familar with GitHub. We need to keep in mind that the documentation is not just for developers, designers and site builders, but for marketing interns, hobbyists, small business owners with a little technical knowledge but needs reference.
TL;DR: The docs as they are now are not a closed system and that conversation is a red herring to making better docs. Github is fine but remember what documentation is and who it's for.
PS: There is a whole project on the MODX Documentation: https://github.com/modxcms/docs
jpdevries
pixelchutes
Mark-H
Summary
The current MODX Docs (RTFM) have a lot of room for improvement. I wanted to discuss what people think are the best ideas for a better MODX Docs and how we can go about implementing those improvements.
Here's a list of features I'd like to see added to the MODX Docs:
Those are just some ideas.
Since they are currently built on top of MODX it makes them very flexible, the easiest first step would be to version control this into git (using something like Gitify https://github.com/modmore/Gitify) so anybody can start making Pull Requests (without the system requiring a login to edit and request-only access).
Alternatively maybe MODX isn't the best platform for the docs, something else entirely could be better.
I'd also like to see some guidelines; perhaps it can be officially recommended that third-party plugins use their own Github pages for their docs, and the MODX Docs are kept for core subjects. That would help keep things focused and maintainable. A lot of the third-party plugins in the MODX Docs are out-of-date and more recently developers have just been setting up their own docs anyway. (e.g. http://bruno17.github.io/MIGX/, http://sepiariver.github.io/cssSweet/ and http://docs.modx.pro/ to name just three)
TL;DR. Overall the MODX Docs aren't the best they can be; let's improve them.