I read it all and like all the ideas.
Devs should at least write a bunch of lines where they explain "How do you get a basic output". I guess that devs like people to use their module (snippet/plugin). Why should they release it to the public if not?
Some other user can take it from there. Someone who can look into the snippet and understands whats in there. Write examples which contain more than "basic output".
This is the place where modx.com jumps in - bringing these people together. We could just open a new thread "Dev searching writer" inside forums.
What does a documentation need?
It needs a guide for the simple user.
"How do I write a new newsletter?"
"How do I upload a picture in my gallery?"
Second (and somehow more important to me) for the webdesigner / admin / webmaster / mysonisgoodwithcomputers:
"How do I setup my first gallery?"
"What chunks do I need for my Wayfinder Menu?"
"How can I limit my newspage to only show the newest 10 articles?"
Someone who dedicates himself to documenting software will be able to read snippets anyway. But it would be of great help, if devs tell them what parameters the snippet will take and what these parameters do to the output.
A single documentation should also let the user know, which version of the module it is talking about. And maybe refer to the changelog which can possibly show how parameters changed or which are new (and need to be documented).
As I don’t write modules myself but understand how they work, I could be one of the guys explaining them. I already thought of a seperate website for my own documentations, but it would be much better to have it all here as an "official" documentation which peole can rely on.
So. Back to work!
I love where this is headed folks. Thanks for all the suggestions and ideas, including the simple solution of Single Sign On for all modx.com properties (we are actively working on this btw and the Discuss based forums are almost baked we’re working on styling and a little more road testing to ensure the integrity of the messages and PMs)
I’ll be compiling the suggestions into a strategy document that we can build on in conjunction with the team.
Keep ’em coming!
Cheers,
Jay
Author of zero books. Formerly of many strange things. Pairs well with meats. Conversations are magical experiences. He's dangerous around code but a markup
magician.
Blog ✦
Twitter ✦
LinkedIn ✦
GitHub
-
- 15 Posts
Idea for add-on : if packman could make a template of doc in analysing source of add-on it will be great, detect parameters and placeholders and put them in text format to doc ( of course the add-on must be writting good ... using for example the scriptproperties array for parameters).
maybe also chunk templates by default put in the doc too
So dev must be just complete doc generated ( a dream ? )
ps : for snippet ok , i have not think about plugins
coding Java Android and NDS
Most addons (or at least the ones that took longer than a few minutes to develop) aren’t packed with packman cause that doesn’t offer enough flexibility nor was intended to provide simple installs..
There’s is something called PHPDocumenter that MODX uses as well for the core API (api.modxcms.com) that relies on comments formatted in a certain way. That would most likely be better than trying to read the code..
When setting placeholders I often use $object->toArray() which just takes all fields - that would mean the script would have to figure out what columns exist from there. I think it’s a great idea, but not really plausible.
I can’t wait to hear about that strategy document Jay - you know how to get in touch with me if you want some feedback on a work in progress.
-
- 107 Posts
Jay, I’m in too if you need any help. I’d like to be a part of this as much as possible because I feel it’s important. As a start the document template should state (not necessarily in this order)...
Name (ex. How to install Gallery and get your first photo album up and running)
Document Authors
Latest Revision (could use number system)
Date updated
MODX version applicable
Document content
The document should include any necessary plugins, snippets, server settings and environment needed to make it happen.
Crawford Paul
Bridgecourt Web Design - Proudly using ModX CMS
Serving Welland, Niagara, Ontario, Canada and the world!
http://www.bridgecourt.com
Document Authors, Latest Revision (could use number system) and Date updated already exists in Confluence, complete with history to see who changed what - so I guess that’s settled.
Should we distinguish between addon "home" pages, and deeper pages dealing with more specific scenarios or tutorials?
Wouldn’t it be possible to do a bi-weekly/monthly Documentation Day?
I’m pretty sure that if we can get Jason & Shaun to work on stuff that they know about and need more info, and others also get involved in a structured way or another (checklists on the forum or the bugtracker) we could make a huge leap forward in a matter of hours. Of course we would need all problems (based on the documentation strategy) reported in the issue tracker before that. But as there’s a backlog with some big stuff in there (system settings for example, but also the class reference I guess) surely we could start with something like that. IRC could be an amazing tool to discuss with others as well if someone isn’t entirely clear on specifics but was assigned (or chose) a certain issue.
You can count on me for something like that!
-
- 107 Posts
That does sound like a pretty cool idea and a good way to really get some substantial documentation developed. I’d be interested as well at least giving it a shot. As long as everyone knew their role and followed the guidelines it could prove to be very valuable.
Crawford Paul
Bridgecourt Web Design - Proudly using ModX CMS
Serving Welland, Niagara, Ontario, Canada and the world!
http://www.bridgecourt.com