mab-recommendations
mab-recommendations copied to clipboard
modxcms
Create MarkDown RTFM
I like it!
To give an example, docs.modmore.com (https://github.com/modmore/Docs) is built with Daux.io, and I think docs.modx.pro (https://github.com/bezumkin/Docs/) also uses it - @bezumkin is that correct?
docs.modx.pro was started as daux.io project, but now it is pure MODX site, that generated from Markdown files. But it still must be compatible with daux.
Anyway - Markdown is great and I want to see all MODX docs in this simple format.
The stated goal is as follows:
The current docs have only a few editors, and are constantly falling out of date.
Is this a valid conclusion?
Converting to a MarkDown system would allow more community members to keep them up-to-date.
I do not know how changing the input format will change the level of activity. It assumes that the input formats (currently HTML and via Custom RTE) are a barrier to update.
Is the real recommendation to make the documentation version controlled text-only md files or similar? If so, please explain in detail. If not, please clarify if you can.
The fact you need to email MODX to get access to edit a specific section is a big barrier, too. ;)
Agreed though, the recommendation could possibly explain the motivation a bit better, especially as moving all the content into flat files in a repository would be a big initiative.
There are currently 116 issues in the documentation request system. It may be opinion based, but I think that having a more direct access for anyone to edit would help keep that number down. It would also allow people who already use markdown for documenting their extras to easily sync their documentation with the system.
If it's community driven, it might not take as much to convert the current system to markdown. Previously it was converted by one person using regex.
Additionally, if there is going to be a major change with MODX Next to how things work, it will all need re-reviewed anyway.
convert the current system to markdown
The current system is HTML and MarkDown is backwards compatible with HTML. So maybe it wouldn't be so bad?
Additionally, a system like StaticCache can be tweaked to build a static HTML structure of an entire site (using $resource->content rather than WGET), so we could really just start with HTML if that makes it easier.
I'd recommend expanding and clarifying this recommendation then to reflect the actual purpose/goal which seems to be to increase and simplify the ability to edit and contribute to the documentation. I would suggest sketching out guidelines for access control and also documenting how to contribute for people who do not regularly use github, since I assume that's where the docs would get managed. The clearer we can be with a recommendation the more easily it can be implemented if agreed upon.
Feel free to fork and commit any additions to the content that you would want in my matdave/mab-recommendations fork. The reason I wrote this was primarily my concern of outdated materials and lack of updates, but I'm sure other reason can be added.
I'd say the recommendation draft is a great idea and the right way. But I'd also say it needs a little more details and a plan about how to achieve that (e.g. like the Restful API Recommendation).
Okay, I'm open to suggestions. I was under the impression that recommendations aren't supposed to get into implementation details.
I've suggested changes to the draft on matdave/mab-recommendations: https://github.com/matdave/mab-recommendations/pull/1
If we moved towards this I think we could also use something like Pandoc to distribute the docs as an E-Book / PDF. Would also be nice to make a Dash Docset.
Just for the public record, I've been working on this. The converted markdown source can be found here and the custom slim app to serve it up can be found here. Looks promising, although a lot of work to polish. Matthias Dannevang has offered to do a design for it.
