DocText: New RTFM Theme Proposal

I've started a project called DocText that aims to do three things:

• improve the RTFM Documentation site
• Release an Open Source documentation template
• Allow anyone to host their own content using the same app engine that will power RTFM

I would love for MODX developers to quickly and easily be able to self host documentation for their projects using MODX contexts. For example, you could create a new 'docs' context, configure ACLs so it is only viewable to logged in users and publish docs as easy as creating new Resources. All powered by the same app engine that *will* power a new RTFM site.

I say app engine because it is more than just a theme. DocText is inspired by devdocs.io which provides several web app like features such as AJAX loading system and offline support.

Checkout (or even edit) the Roadmap for DocText:
https://github.com/jpdevries/doctext/wiki/Roadmap

View the Contribution Guide:
https://github.com/jpdevries/doctext/wiki/Contribution-Guide

You'll see on the Roadmap that DocText isn't planning on becoming an official MODX project until version 0.8. That is why it is still on my github repo, not the official modxcms one.

Great idea (though I'm not crazy about markdown). I wish I had time to help.

Are people really going to have to learn Git, Ruby, Ruby Gems, Sass, angular.js, node.js, markdown, and Grunt to be able to contribute? That's a pretty tall order. I'm a fairly experienced developer and the Contribution Guide is largely incomprehensible to me except for the Git sections.

Quote from: BobRay at Dec 11, 2013, 10:01 PM

Great idea (though I'm not crazy about markdown). I wish I had time to help.

Markdown editing is a hope of mine (probably using EpicEditor) but whether or not it would see the light of day through RTFM I'm not sure. Reason being, it wouldn't be much use unless the content was being saved as Markdown on the server. If it were added it would be as an option that defaults to WYSIWYG.

Quote from: BobRay at Dec 11, 2013, 10:01 PM

Are people really going to have to learn Git, Ruby, Ruby Gems, Sass, angular.js, node.js, markdown, and Grunt to be able to contribute? That's a pretty tall order. I'm a fairly experienced developer and the Contribution Guide is largely incomprehensible to me except for the Git sections.

Depends on to what they are contributing to. You don't really have to learn Ruby, Ruby Gems, or node.js. You just have to install them to use Grunt and Sass.

I don't think because a project utilizes one toolkit or another equates to taking freedom away from contributors. Pull Requests can be submitted with raw CSS and unbuilt JavaScript for contributors that choose to do so.

Bob I know how much you love a good article and this is a great one by Chris Coyier. He writes an introduction to Grunt and why it has been found to be so useful by the industry.
http://24ways.org/2013/grunt-is-not-weird-and-hard/

Grunt is one of those fancy newfangled things that all the cool kids seem to be using but at first glance feels strange and intimidating. I hear you. This article is for you.

I understand the hesitation to adopt any new tool or process. Heck, it wasn't more than a few months ago that I started using Grunt after pair programming with a few front end developers that completely sold me on it. It's not as scary as you think, I promise. It even reminds me a little of MyComponent!

I'm not frightened, though others might be. I have at least a hundred projects and a) don't have time to integrate Grunt with them and b) the cost/benefit equation doesn't look like it would pay off. MyComponent will already minify and concatenate .JS files and there's only one .CSS file per project (and they shouldn't be concatenated across projects). I also haven't had time to integrate SASS with them (and won't any time soon), so there's nothing to gain there.

The one task I'd like to use Grunt for is processing the e-version of my book, but several of the steps can't be done from the command line, so that's out as well.

(As an aside, if anyone ever asks you to do an e-book version of a 800 page book full of lists and code, just say no)

It is a great article, though.

The one task I'd like to use Grunt for is processing the e-version of my book, but several of the steps can't be done from the command line, so that's out as well.

Now I'm curious. What are the steps that can't be done?

Exporting from Word to compact HTML (I know there are alternatives, but I have a PHP filter that depends on Words particularly odd HTML), editing the metadata in Calibre, conversion in Calibre, and exporting specific versions from Calibre.

Even if they could be done from the command line, a batch file would probably be a better option since there's only one source file and I don't want to run all the time-consuming steps whenever it changes.

No disrespect intended here to the amazing work that's being done. But I understand that MODX resources are thin on the ground. I'm looking at this and wondering why it's being given attention when there are so many other worthy projects that should surely get prioritised, not least MODX 3?

Again, the RTFM sounds neat but I'd rather see beginnings of MODX 3

Quote from: eladnova at Dec 14, 2013, 03:25 AM

No disrespect intended here to the amazing work that's being done. But I understand that MODX resources are thin on the ground. I'm looking at this and wondering why it's being given attention when there are so many other worthy projects that should surely get prioritised, not least MODX 3?

Again, the RTFM sounds neat but I'd rather see beginnings of MODX 3

There is no doubt resources are thin. That is why I look for ways to create projects that have multiple applications. For example this project and Matboard both serve as proof of concepts for MODX 3.0 in their own respective.

With Matboard, I'm looking for contributors to to create simple assignments using various toolkits.
https://github.com/jpdevries/matboard#matboard

Matboard will help us learn and discuss which of the various toolkits are most applicable for 3.0. DocText is born out of internal R&D on responsive design, scalability, and creating rich web apps powered by JavaScript.