How To Videos+discussion
Any suggestions for how to improve our how-to videos?
Thanks, these how-to videos really go a lot further in explaining Wagn than other documentation. A suggestion for improving is going even more in this direction: describing an entire REAL use-case. Putting effort into a realistic example cannot be overrated when trying to describe something as complex (and powerful!) as Wagn.
For example, including a sentence like "It's easy" as a separate card might even turn some people off as it seems a really complicated way of doing nothing special :)
In my opinion a good example would be a simple bugtracking/ticketing system: basically you need an Issue cardtype, which is a form with some free-text data (description, title...) and some selection boxes (e.g. to assign issue to a user, to choose priority...) and most importantly you need some views (filters) to: list only recent issues, list only issues assigned to me, list only issues with a high priority... I've tried doing this on my own but have been struggling with the view/filter part.
All that said, Wagn seems to have enormous potential but it's really difficult to explain and get the user interface right. I'll try my best by exploring more and hopefully write a howto when I manage to create a mini-app like the one desribed above.
--Dare (Not signed in).....Mon Aug 23 22:49:52 -0700 2010
that was me above :)
--Darko Bodnaruk.....Tue Aug 24 08:51:03 -0700 2010
Thanks, Darko. I think you're right. In the next round of videos (which shouldn't be too far away), we should do a more REAL use-case.
One challenging thing is not to introduce too many ideas at once. The idea with "it's easy" for example, was to do a simple inclusion before I introduced the idea of formatting. If it was just that one card with that little bit of text, it wouldn't make sense to create a new inclusion. But it does make sense when you're setting up a pattern, which we get to in the fourth video.
Maybe the guideline should be to make sure every step of the way makes sense for its own purposes, so that you don't have to make it through the entire sequence to understand the rationale?
As for filters, most of that work should happen in CQL. I haven't done a WQL video yet, in part because there's not really a graphical interface for it yet, but I hope to do that in the next round. (I get why you're using the term views here, but that term will be less helpful in finding the best way forward for what you're talking about than Search and CQL).
--Ethan McCutchen.....Thu Aug 26 15:23:45 -0700 2010
I realise your discussion was a little while ago but thought I'd throw in my 2 cents.
First of all, I'm totally new to WAGN - so far I've watched the videos a few times, have briefly played about with a local install and am currently trying to put it on my shared host (but that's another story...).
WAGN is obviously a hugely powerful and flexible system that will inspire whole new website systems - and I find the style of the current videos very approachable. So huge respect for that and all the work you have done.
From the topics and presentation this documentation looks like it is aimed at the end (power) user rather than a site developer (which appears to be where Darko is coming from). Whilst the very nature of WAGN blurs these traditional boundaries I still think there is a distinction around which to divide the documentation. So the following mainly relates to end user documentation but could have relevance to developer documentation too.
I completely understand Darko's desire to put some practical implementation into the introduction but I feel that explaining the way the system works with a usage-case type tutorial can easily detract from the rich possibilities of such an open system (especially with a fairly traditional usage case).
"Don't think about purple rabbits!"
You thought about purple rabbits, right? It's impossible not to - linguists/hypnotists/con-artists/psychologist have known this for years. What do I mean by that? Well...
From previous experience I know that I find an introduction to any highly maleable system based on a usage-case greatly influences the way I approach using it.
Take Rails for example:
- I first saw the 15-min blog system screencast, so every rails app I thought of had to evolve from a very traditional blog system
- then I did a tutorial on shopping systems, so rails became some kind of blog/ecommerce creator
- then railstutorial.org which creates a twitter clone, so now rails is blog/ecommerce/microblog.... etc.
This makes seeing the components and fundamental functionality really hard without those point-of-views and to break this you have to work through many examples and stand on your head a lot.
Whilst I personally learn best by analogy, I think this too would be restrictive for similar reasons.
Also, whilst screencasts are really practical and (relatively) quick and easy to produce, I think that a very simple illustration of the concepts before going into the clicks and syntax would be useful. I'm not talking about facile fancy character animations (a la google), maybe just simple vector illustrations/flow-charts as you talk through the concept.
I could go on but to keep it brief(er), I think that each of your topics could be split up as follows:
-1 Introduction of concept with simple diagrams (video if possible, or text and image)
-2 Video of how this works practically (like the current screencasts)
-3 Links to cards of Possible (< very important word) Case Usages (use your red links and let the community fill it in) - each of these cards could have a description of possible implementations (text/image/screencasts), discussion board, further reading links...
-4 Link to developer discussion of this topic (if relevant)
You could also have cards that link all the cards of one type of Usage-Case (blog, ticketing, etc) together, to form a usage tutorial including each of the topics for that usage-case.
Hope this makes some kind of sense - I'm by no means a documentation specialist - do get in contact if it doesn't. I'm very excited by WAGN and looking forward to all the interesting things people are going to do with it.
Thank you once again and all the very best,
Steph
--steph.....Fri Oct 22 16:20:37 -0700 2010
I think that a detailed explanation on how to install Wagn it will be useful to chaps like me, who are designers tinkering with write codes to better develop beautiful and truly functional web applications. I downloaded the installation pack from Giihub, but when I tried to "run rake wagn:create"&"run ./script/server" command, didn't worked. Should be done in cmd window? or irb window? Where should I unzip the package? I'm not a programmer, so is difficult for me to deduce how to do things when I don't have detailed instructions. I'll keep on trial-and-error till I acccomplish the thing, but is very hard.
--Fernando Bezerra Santa Rosa.....Sat Jan 01 15:01:34 -0800 2011
I, just tripped on this while looking for a simple wiki engine for my company. I must say that's pretty impressive ! I really love how it maps to both OOP and ... common sense. I really wonder where this will go. Congrats !
(ps : i love it, except for the stylesheets. All this christmas aggressive green + eastern europe depressive hospital green + executive windows 3.1 blue-gray + blocky bloat blunt round-edged header thingy... sorry, but it hearts my feelings)
--impressed (Not signed in).....Mon Jul 11 17:22:39 -0700 2011
That's got to go down as one of the comments of the year!
--Ethan McCutchen.....Tue Jul 12 07:17:03 -0700 2011
I'm with the previous commenters on the power of Wagn, but am still struggling with basic implementation matters.
I understand Steph's comment that a worked out case would probably bias users, and agree that descriptions or links to alternative usages should be added (e.g., Stephs #3). But, there has to be a starting block, and I agree with Darko that a basic bug-tracker would be an ideal starting block. I'd love to see individual cards devoted to each case/feature example (e.g., adding a radio button list to a bug-tracker would be a single card) with a summary of the prerequisite concepts and the corresponding CaseFeature cards for the current case, summary of the basic steps, video, and then links to comparable features in other case examples and the table of contents for the current case example.
Examples of suggested CaseFeature card sections for a "Bug-tracker - add a file upload option" card (some of which could obviously be general inclusions):
* Prerequisite concepts: CardTypes, +cards, *content cards
* Prerequisite examples:
-- "Bug-tracker - create an Issue cardtype"
* Summary of basic steps for "add a file upload option to a form":
(1) on the +*type+*content card of the form being edited (e.g., for an Issue card "localhost:3000/Issue+*type+*content")
(2) enter edit mode (i.e. double-click the content, or click the card's "Edit" link)
(3) enter "{{", the name of the text to be displayed, "|", "type:file", and "}}", for example "{{upload related file|type:file}}" [I know this is being deprecated, but I haven't seen an example of the new approach that will work on my local version.]
(4) save
(5) test the revised cardtype's new or edit form
* Comparable feature in other case examples: "Blog - add a file upload option", "Commerce site - add a file upload option"
And as for impressed's p.s. comment - yep, not a fan of the green theme. The current Wagn.org's "bruce layout" is mucho, mucho better!
--eidosabi.....Wed Jul 04 19:34:08 +0000 2012