We launched new forums in March 2019—join us there. In a hurry for help with your website? Get Help Now!
  • 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!
      • 21838
      • 284 Posts
      Quote from: dogo at Jun 17, 2011, 08:16 AM

      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?"

      Can you please file a bug in issue tracker about every ADDON where you expect improvements like that. As I said, make it as easy as possible for docs writers. Bug-tracker is the easiest way for us. smiley
        MODX Free Template Base: MODX-Boilerplate | my blog (lots of MODX stuff) | my gitHub (translations) | MODX User Groups Germany (Facebook)
      • 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. BlogTwitterLinkedInGitHub
          • 2048
          • 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.
              Mark Hamstra • Developer spending his days working on Premium Extras and a MODX Site Dashboard with the ability to remotely upgrade MODX and extras to make the MODX world a little better.

              Tweet me @mark_hamstra, check my infrequent blog at markhamstra.com, my slightly more frequent ramblings at MODX.today or see code at Github.
              • 26422
              • 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?
                  Mark Hamstra • Developer spending his days working on Premium Extras and a MODX Site Dashboard with the ability to remotely upgrade MODX and extras to make the MODX world a little better.

                  Tweet me @mark_hamstra, check my infrequent blog at markhamstra.com, my slightly more frequent ramblings at MODX.today or see code at Github.
                • 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!
                    Mark Hamstra • Developer spending his days working on Premium Extras and a MODX Site Dashboard with the ability to remotely upgrade MODX and extras to make the MODX world a little better.

                    Tweet me @mark_hamstra, check my infrequent blog at markhamstra.com, my slightly more frequent ramblings at MODX.today or see code at Github.
                    • 26422
                    • 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
                      • 28215
                      • 4,149 Posts
                      Good discussion so far, and thanks to all for the initiative on this. The core team tremendously appreciates it.

                      I would highly recommend people file "missing gaps" in the documentation here: http://bugs.modx.com/projects/docs - This will give us a nice running list to start from. Also, it notifies Jason/I/core team what topics are still needed for documentation; with such a massive project, sometimes it’s difficult to remember if everything is documented fully.

                      Thanks guys.
                        shaun mccormick | bigcommerce mgr of software engineering, former modx co-architect | github | splittingred.com