Quote from: OpenGeek at Oct 03, 2009, 06:11 AMIn any case Stephen, thank you for the time and effort you have put into this conversation. We may disagree on a few things, but your thoughts are very much appreciated regardless and have certainly been helpful to our efforts in many ways. I hope we can continue challenging each other’s ideas here.
I have appreciated this thread, it’s definitely done by gentlemen, on both sides.
But, as a modx lover, I fear that time spent in writing such good and long answers, and documentation, could slow down work on other stuff (bugs, enhancements, etc.), because it seems that those engaged in conversations and very helpful answers not only in this thread, but in the whole forum, and writing big pieces of documentation too, are also involved in several aspects of modx itself and modx-related stuff. I really have no idea how you can do that, hat down!
So here they are my 2 euro regarding the lack of documentation issue, I’ll spend some time for a pretty long post but I see it as my investment to let modx coders focus on what I love they do, i.e. doing modx and not writing docs!
Hey I’m joking, write whatever as much as you feel fits
By the way, yes I was joking but the joke was based on a real sentiment: docs are hard to write, and to maintain.
My proposal is to let stuff like movies, animals, chemical compounds and whatever else have their word-by-word wiki-like two-and-more pages "docs", while have software like modx - where the purpose is to get something done - focus on "docs by working examples", a bit like the
Mootools 1.11 demos just to start figuring what I mean, where one can understand stuff just seeing it into action (and getting excited) and then looking how it’s done browsing the internals (in Mootols 1.11 demos, the "js code | html code | css code").
So the time needed to write a good documentation, from my point of view, would instead be better spent by creating a "system", a kind of self-transforming multiple-instances virtualized modx installation available online to users, where you can select one of the available examples and - voila’ - it shows a simulated modx environment, where you can see the project running, explore the manager, look into the files in the filesystem, read some rows of text explaining stuff, etc. and eventually with pretty every element (resources, elements, documents, files, folders, etc.) supporting an "?" icon that when clicked makes a popup appear with some words of explanations (of course no explanation, no "?" icon).
Complementing the online service, a tool should be provided to "build" those examples, and upload them into the user-contributed category. Something like having a clean installation of modx, with a "reset" button to make it clean. And then you make something with it working normally like you do when developing stuff, and then click a button and it creates a zip file with all the instructions needed to the online "system" to build the example and add it to the user-contributed examples repository.
I feel it’s sure hard to make this kind of system, but I wanted to throw these my two dimes because I know that many times it’s easier to *do* stuff (especially for coders), than explaining and write how to do stuff; but also, many times it’s easier seeing how someone has done stuff (if it’s focused on a single issue, and not bloated with unnecessary or unrelated things, i.e. noise for the purpose of the example) rather than reading through a detailed explanation.
I’m not sure that it’s clear what I’ve written, so I’ll make an example:
I want to see how I could do a simple blog in modx; so I go to this service/site, search in the search field, and some blog construction examples pop out. I click the one with most votes, some gears mumble, and then the page sports a sidebar on the left with some controls, and on the right I see a basic and working blog in action. In the sidebar, I have those controls, e.g. "See Full Manager", "See delta-Manager", Execute", "Browse delta-filesystem", "Readme", and whatever useful stuff this service could have. The "See delta-Manager" thing I imagine is a modx manager where you see only the things added/modified to make the blog; similarly, the "See delta-filesystem" thing I imagine is a popup where you browse modx folders and files, but just those added/modified to make the blog; and when you click on a file, it shows the content with appropriate syntax highlighting.
Then back to results, I try another blog example, etc.
Examples and users are community-rated, so eventually I’ll start exploring the most valued examples popping out from my search queries.
Hope this makes sense. I repeat, writing docs is hard and time consuming; most of the time, developers have no time to explain how they do things, or they’re not good at it as in making stuff. If they had a convenient way (build tool + web service) to explain stuff just by doing it, I’m confident that the "docs" would grow crazy, or at least enough to grasp things for willing users.
And most of the time, non-developers don’t write the docs for this kind of projects, or they need a developer explaining something now or then in order to write about it.
So:
1) non-lazy developers know how to do stuff, but have no time or are unskilled to write about it;
2) lazy developers know how to do stuff, but won’t write about it;
3) non-lazy non-developers need developers to know how to do stuff, for writing about it; so back to 1) and 2)
4) lazy non-developers won’t ever write modx docs (if not payed), count on it.
So the solution I’m proposing here is to let developers and non-developers easily create and publish, in a single place, straightforward examples on how to do stuff with modx, and a convenient way for the users (both developers and non-developers) to enjoy them, understanding a lot of cool things (and get excited seeing stuff in action immediately).
And don’t forget the search features, examples and user’s ratings, tags, etc. to help users in finding what they’re searching for and promote contributions.
Contributors, will have to:
- load their modx-like environment (modx example builder tool)
- click the reset button
- make their example work on localhost
- fill the mandatory example metadata fields (title, description, etc.)
- click the example build button
- click the upload example button
- complete the signup wizard if it’s the first time they upload an example and still don’t have an active account in the system
- feel good as they receive statistics on impressions and karma votes for their uploaded examples
Moreover, the service could also be used by developers to browse their own examples, as a reference when doing their work: a set private/public property in the examples metadata would help in this regard.
Sorry for the long post and for being not able to build myself such a thing, I hope the idea is enough for you or someone else.
Go modx, keep up the good work.
