Hi Scott, I’ve been working on the design of the extension and analyzing different implementation strategies. In this post I describe the requirements I think the extension must satisfy. On the other hand, there are some questions regarding to Atlassian features that I’m not sure if must be included in the extension also.
A goal that I think is important to achieve to produce a much more productive extension is reduce to the minimum the amount of programming that a developer needs to write to use it. Could be very useful that the programmer add the notes via the web interface instead of write code. In this case, the note information (title text, body text, buttons text) would be stored in special tables in the database, instead of code text files. To achieve this, probably could be necessary extend the functionality of some core classes of Yii. However, this doesn’t means produce a hacked or patched version of Yii. This could be achieved naturally using Yii extensibility mechanisms such as inheritance, filters, attached behaviors, etc.
Seems reasonable to me.
In summary, I understand that the extension requirements are:
- Position behavior: The note will appear next to the control and will have a small arrow pointing to it. If the user scroll the page, the note accompany the control in its new relative position.
Agreed.
- Appearance customization: The extension should allow to change the appearance of the note with relative ease and configure some aspects of their behavior. For example: whether the note will appear in a "pop" or "fade" mode (configuring transition ms), etc.
If this can come out looking nice, I have no objection - sometimes fades just show up as choppy and detract from the user experience, but I’ll leave it to your expertise…
- Online tutorial creation: This is the goal mentioned at the beginning. It would be very productive if each tutorial could be created in "online mode" by developers (or administrators).
Would be nice, but really this is the sort of thing that would be implemented by a developer up front to display the use of a web application, and to train new people on it. If it involves some straightforward coding, or code modification, I don’t think that would be the end of the world since in order to have a Yii application and this (future) Yii extension installed, one would have to have a basic knowledge of coding. If it’s easy to do, great - but if it’s going to be half the development time making it “non-coder friendly”, I think the main users of this are going to be developers with the ability to manipulate some code.
- Multilingual support: To enable the integration in multilingual sites, the extension should also allow the entry of the text of each note in different languages, and display it in the current user language.
Perfect - I’ll actually be utilizing it primarily for a Spanish-language based web app, so this would be awesome. I see you mentioned English isn’t your first language either, though I couldn’t tell from the quality of the English in your writings (as someone spending a lot of time learning Spanish now, I can appreciate how much it takes to get where you are with your English!).
-
Security: If editing the note is made via web, only users who are administrators must have access to create or edit notes.
-
Documentation: As the extension will be shared with the community, is very important the internal documentation (in the source code, PhpDoc style) and external documentation (step by step guide in html and pdf). English is not my mother tongue, but I can get a human translator to do the sintactical and grammatical review.
I can work with you on the English documentation if you like, though your English is great.
- Code quality: As the community will have access to the source code to modify it and improve it, code will be developed in compliance with the naming conventions of Yii, following a consistent programming style, including structured error handling, etc.
Sounds great.
- Support: After extension creation will be necessary support to developers who wish to use. I will give free support via email. My desire is to do this indefinitely, but I guarantee to do that for at least 6 months.
Awesome and appreciate the offer.
- Maintenance: After extension creation will be necessary maintenance (bugs fixes, enhancements, etc). My desire is to do this indefinitely, but I guarantee to do that for at least 6 months.
Again, sounds great and I’ll join you on fixing and improving it.
Besides watching the video of Atlassian, I registered in the website and used his platform. There are some Atlassian features I would like to consult you if should be emulated also:
- Organization: Atlassian tutorials organizes multiple "courses" that are composed of several "classes" with several "lessons", each of which has several "chapters" (tabs). Should the extension support multiple tutorials? If so, what would be the organizational structure? Should show the approximate time of each lesson as it does Atlassian?
I’d go so far as to call this a necessary feature, having an organized step-by-step process for someone completely new to a system to go through to learn it. On the other hand, one should be able to go straight to a particular tutorial (“How to add a new user”, for example), if that’s what they need refreshed upon, but the main use of this I see is similar to what Atlassian does - getting new people up and running on a new web application with a more interactive environment than a text or video tutorial. Having a notation for the approximate time each section ought to take seems like a handy addition.
- Progress tracking: Atlassian also has the ability to "remember" what tutorials a user has completed (even partially). Should the extension also provide this functionality?
I don’t think saved progress tracking is a priority, but if it’s not a grand project to implement, OK. In my particular application, this tutorial would only be used by people who already had an account from within the web application, so might be possible to tie the saved tutorial information to an existing user account?
- Automatic typing: Atlassian sometimes include in the notes a "Type for me" button that automatically insert in the textbox some text. Should the extension provide such functionality as well?
Easy to implement through Javascript, and would be helpful to a user for an example of what to input if that’s not yet clear to them. I like this.
I want to ensure that all requirements are included. There are any other requirements of the extension that are not included in any of the above?
No it looks like you’ve thought everything through pretty well - I’m sure things will come up as we go through it, as they always do, but can tackle them as they come up.
Best regards,
Leandro