Why you guys didn't put a tutorial, in writing, for creating a custom module?



  • It is clear that there is a simple page to discuss the way to create a custom module and there is also a video one that have been posted on Youtube, however, it is hard to say that these are appropriate tutorial documentations.

    Notes that 'documentation' means 'Material that provides official information or evidence or that serves as a record:
    you will have to complete the relevant documentation', in addition, it is alsl referred as 'The written specification and instructions accompanying a product, especially a computer program or hardware' (Oxford Dictionary). You cannot just record what you did to create a custom module as a video and go through it quickly because some persons who do not have any idea that how Laravel or Asgard works may not catchup what you're doing. Here're some issues you may want to consider:

    • The IDE you are using in the video is not used some users' one, so your demo operations may not as same as theirs. Some auto-completion process may not available for some other IDE. So these people may found they are really hard to follow up because they have to manually type them in.

    • For some unknown reasons the outcome after executing one command may not be consistent between the video and the actual user. For example after creating a module it will generates a 'Translatable' line in the entity but not in the video. If any user does not remove that line it will constitute an error.

    • It is extremely difficult for users, who follow that video and have to type everything and then the system reports an error, to debug by referring to the video. They have to read all your actions and any lines on the screen. It may constitute a negligence by failure exercising a reasonable care of presenting a proper documentation to end users (s 43, Wrongs Act 1958 (Cth)).



  • I (almost) completely agree with @Prinz-Engen

    • The current documentation, despite it's been useful for me, is now pretty scarce and needs more improvement and detailed cases, as well as examples and a full API documentation. An explanation about how is the CMS integrated within the Laravel base app (how is routing done, more details about the "Repositories", etc), would be great too.

    • About the screencasts, some of them are a bit hard to follow, especially the front end one (

      ), in which you have to guess the view files in the first minutes of the video are placed in the theme and not in the module itself [and those "pre-made" views in the video, most people get lost there, because it's confusing from where are you taking it].

    • About the IDE... It's up to any user to use whatever they fit their needs, but PHPStorm, being proprietary, it's not available to the whole public. Anyway I don't care about the IDE or whatever text editor you use. The only thing I'd suggest, is keep to a minimum the use of boilerplate generators in the screencasts (e.g. creating Classes), or at least, give more details about what the boilerplate includes. I use Emmet for instance, and yay, it saves you time and typing, but in a screencast/tutorial that's not the whole point.

    Having said that, I would like this lines to be understood as a positive critic. I know making documentation and screencasts is very time consuming, and requires time and effort. So I'm thankful for the efforts the AsgardCMS team has done, and I'm up to collaborate to the improvement if needed, not just demanding. :)


Log in to reply