Dear Dan,
I am very pleased to see a developer willing to respond to a very beginner's
output (input to you, output from me :-P ). It is highly appreciated. In
return to you msg, I'll write down my experiences with BoltWire below.
Before that, however, I do have one question: is it true that a
non-programmer (some one who is not willing to dig into the lines of codes)
should not run a website using BoltWire? If your answer is yes, then you may
just skip the rest of this msg and I won't be bothering you any more. Yet if
you have the other answer, maybe you can take into consideration some of my
suggestions that follows. Here it goes.
A week ago I found this software by chance and decided to give it a try. In
just about 5 minutes I got it up and running, including change of language.
A big shock! I am sure there are people who can do the job in 5 seconds, but
for a non-programmer and a beginner to this kind of software that was a
record high. Before this one I tried the very popular WordPress, Moodle and
Drupal, none of them gave me such a good experience in setting it up. For
this all of you developers deserve a BIG APPLAUSE.
In the next one hour or so I was quite happy for being able to change the
content of the main page (without understanding all of it, of course),
changing the side menu and the top zone, installing some eazy plugins.
Great! Then I started to try more things like stying, coloring, customizing
actions and so on. Pretty soon I realized that I needed to go through some
documents before I could go any further. This then led to a three day
nightmare...
The first thing that confused me a lot was the markups. I know you are all
familiar with the wiki things, but I am sure there are way more people out
there who are just not. There is a nice table in the document for sure, but
new users, especially non-programmers, just don't remember so many things in
one time. Every time I saw something like {page::var} or [[link|label]], I
would be like: "wait a minute, I remember seeing this somewhere...", and
ended up spending more than a few minutes just to find it again, then lost
the focus of where I was. No good. Now I realize they are not so difficult
after reading them for some days, but a week ago they were really like
Klingon to me. I think it is a good idea that a document helps the readers,
less experienced users in particular, stay focused on the subject and not be
distracted by things they are not yet familiar with. After all these people
are the target of documentation, aren't they? One way to accomplish this is
to offer a chance to remind the reader of the meaning of special terms or
patterns every time they appear, without leaving the page he or she is
reading. I am not sure how to do so, I am just suggesting what to do in a
non-programmer's point of view.
The second frustration came from finding inside the box the new pages just
created. It took me almost half an hour to find them listed in the
non-system pages. In the "About BoltWire" page it says
...BoltWire allows you to not only customize content within a site, but also
> the engine itself––from right within your browser!
>
I am sure you did the nice work, but you forgot to tell "other people" how
to do that. I had to spend half an hour blind clicking to find the newly
created pages. Maybe the word "site" says it to you, but to a non-native
speaker like me it just doesn't do. I know this software is still not yet as
mature as others like Drupal or WordPress, and no one should ever blame a
high school student for not able to work out calculus problems. Still I do
recommend reducing such kind of barriers at the beginning, not the end.
Putting some examples in the documentation is a good idea. But better yet, I
suggest to have an action or some thing alike BY DEFAULT (not that "you can
modify the code" or "you can install this plugin" thing) to allow easy
access to content pages. I am sure EASE OF USE is one of the main
philosophies behind BoltWire, isn't it?
The next thing is the authorization system. I got the idea that BoltWire
allows sophisticated, page by page authorization, you have explained it
well. However, I never got how to do it. I just couldn't find in one place
examples and clear explanations on the syntax of the text in the
authorization files like these
*: @member
> action*: @editor
> code*: @editor
> group*: @editor
> group.admin <http://b338/%7Ewcy2-2/blog/index.php?p=group.admin>: @admin
> login*: @editor,@key_register
>
That's right one should've grabbed the idea in a few seconds, I know. But
what does it mean by key_register? What is key_wikiblog? What is authkey?
When to use them? And how? I simply found no easy answers. It would've been
nice if there were some examples coming with the explanations on the syntax.
Even more, I'd like to suggest you build an user interface with a list or a
group of checkboxes for clicking without typing. It increases the chances of
user erros if one has to type in the text manually, for the spelling must be
correct. You might think its no big deal but for me if I don't understand
the meaning I would never remember how to type it right. I remember reading
"...cuts down on user errors..." in the "Pange Names" section of the page
titled "Creating Pages". If cutting down user errors is one of the concerns,
this extra suggestion should make some sense.
And there is the file naming thing. Seriously I do not find it a good idea
to leave the users to name their content pages. What users concern most are
the title and content, not the file name of their pages. Especitally when I
read about the nice hierarchical system with the naming convention, I was
even more certain that you should not leave the users to name their page
files. Why not? You've said that: "... cuts down on user errors...".
Another point in the naming convention: it seems to me not so consistent? I
remember seeing names like code.xxx.skin as well as xxx.skin. It seems some
times users should put their own 'xxx' some where between the default page
levels while other times just higher (or lower?). Maybe I simply didn't
spend enough time to grab the whole idea, but at that time I was just fed up
with confusion and couldn't do anymore. I couldn't find some examples to
show here because I found myself lost again going back to the documents. I
do not suggest you to clarify this in your documentation. Instead, I suggest
you not to leave the users to name their page files. Keep file naming
consistent within BoltWire and cut donw on user errors.
Back to the documentation thing. A little suggestion to the use of terms in
it.I know you are so familiar with the variables since you play with them
everyday, but useres don't need to know the name of the variables. BOLTadmin
and admin are simply not the same thing for non-experienced users. When I
read "login as a BOLTadmin" I really got confused whether to type "admin" or
"BOLTadmin" to login as an administrator. Of course it took me no time to
figure out but I imagine there could be quite some people get stuck by such
things. Again if you think a fool like me should not even bother to run a
website, I can tell you that I am using Drupal and it's now taking off. The
setting up stage was a bit pain to me but after that, it was a lot easier to
get things work AS UNDERSTOOD. I am not saying Drupal is a perfect solution,
but for now I got way more farther in three days with Drupal than with
BoltWire. I think there are two main reasons, one of which being that there
is no such confusion in their documentation. Even though reading your
documentation was a joy for the fluently written English, terms like that
alwasy got me stuck. My suggestion on this is to remove all the unnecessary
BOLT- prefix in the documentation, to keep it easier to beginners.
I said two main reasons above but only mentioned one, what's the other? It
is that I could change settings mostly with a GUI, no need to edit the
files. We all know why modern operating systems spread out so widely. It's a
fact. If BoltWire is aiming at something more than a concept-proof, building
some easy-to-use GUI's is a must.
Other minor things below:
- I couldn't find an easy way to assign a member to a group (an action or
button or something that requires just clicking/typing but no file
editting).
- I couldn't logout by just one click.
- Couldn't get to the page
http://www.boltwire.com/index.php?p=resources.solutions.gui to download
the gui buttons for editor.
Well, I'd better stop here or I won't have time to get my own work done.
Thank you very much if you have come through all this. I'd like to mention
again that I am not a programmer and a very beginner to this kind of
software. Maybe some of my points are just too naive and wortheless, but I
think that pretty much reflects a beginner's feelings.
And once again, I'd like to say that I do see a hope in BoltWire and looking
forward to seeing it fly high.
Sincerly,
Vincent.
2009/5/21 The Editor <[email protected]>
>
> I have appreciated all the discussion on Mark's excellent post. It's
> not the first time we've had this discussion, but it seems the last
> overhaul of the documentation met some needs, so it has been awhile.
> In other words, I think we have made some progress with the
> documentation, but we are not there yet. Here's few responses to
> various points raised by different individuals:
>
> Mark: For example, I still do not know the difference between
> "handbook", "documentation" and "help system".
>
> The documentation is the complete set of doc pages on the BoltWire
> site. If you look at the first column here
> http://www.boltwire.com/index.php?p=docs you will notice the Handbook
> is one subset of the doc pages. The Handbook is designed to be a
> master list of all the commands, conditionals, functions, markups and
> variables in BoltWire. The five main building blocks. Kind of a master
> list of the stuff BoltWire understands. All the other pages deal with
> everything else.
>
> The Help system is a built in, dynamically generated function in
> BoltWire that can be handy when trying to figure out how something
> works. It is mostly helpful for those who know php. To study the
> various time functions for example, just add &help=time to the url and
> right in your current page help information drawn directly from the
> source code is visible. I don't recall if it's turned on or off by
> default. But you can try it on the BoltWire site easily enough. I
> like it because I can see the actual code and decipher what the syntax
> is supposed to be, etc. I rarely look at the docs--I go straight to
> the code. It is also a shortcut of markups when the user is not logged
> in.
>
> Mark: BoltWire is used for blogs, forums, wikis, PIM, websites,
> webshops, etc.. I think all these specific wishes would best be served
> by making tutorials for each.
>
> Agreed, this has been our real need. The problem is, who is going to
> write them. I'm afraid I don't have the time. It would be nice if
> those who develop some specific BoltWire application to document how
> they did it for the benefit of others. But it's time consuming
> process. So the docs can only grow in this area as we have
> contributors. The other docs grow by adding a piece here and there as
> some question is answered on the mailing list. But these tutorials
> take a raw investment to get the initial page off the ground.
> Personally I prefer editing to writing...
>
> Mark: I think the documentation would be best if it is split up into
> the different aspects of boltwire. I would make the following
> categories:
>
> If you look again at the main docs page (the left column) you will see
> we already have some of these sections. Including an "administration",
> "handbook", "extending BoltWire", "layout", and a "start" section (not
> showing) corresponding to some of your suggested categories. I'm open
> to making changes to the outline, but I would rather tweak what we
> have than try and start over again from scratch. Suggest one or two
> specific changes you'ld like to see to start with? And then we can go
> from there...
>
> Markus: For Dan it is almost by definition extremely challenging to
> write documentation exactly the way a new user needs it
>
> This is more of a problem because I almost never use the
> documentation. If I can't remember how to do something, I just open
> the source code and take a quick peak. I find it quicker and easier to
> get information that way. So I almost never even look at the
> documentation. Really, there's no way I can keep up with that.
>
> But the problem is bigger. Even new users are going to expect the docs
> to be different depending on their background and what they are used
> to. We all have different ways of thinking, different backgrounds, are
> use to different software prior to using BoltWire, so any way we set
> up the documentation will make it easier for some and harder for
> others. Mark has good suggestions, but I don't think it's that far off
> from what we have. If you use the hierarchical list. I personally find
> the alphabetical list more useful (the right column). And others just
> use the search feature. So we want to give users several options, and
> keep the organization at least reasonably logical. Part of learning a
> piece of software is just learning how the documentation works.
>
> Linly: Btw, Dan has mentioned a "rating/flagging system" for the docs
> here:
>
> I'm open to it. It's another option. But there hasn't been too much
> demand, and I'm not sure how it would work for the docs. I think it
> might be more useful for the solutions. At least rating and tagging.
> For the docs, some kind of flagging system would be nice, where
> questions could be asked. We could have simple comment boxes, and then
> keep a list of recent comments so issues could be addressed right
> there on the site. That would probably work well enough... To set
> aside time to develop these things I need more urging though. I find
> myself more enjoying BoltWire these days, and less developing it.
>
> Karl: One area that I feel would help the documentation area would be
> more examples.
>
> Yes, the more examples the better! Anyone with a member account is
> able to add examples. I'm not so keen on popups or subpages, and would
> probably just as soon weave them into the doc page and put them in a
> code tag. It makes the pages longer, but it's all there together at
> your finger tips. Tooltips are ok, if you notice they are there. The
> bigger problem is getting people to contribute the examples... Almost
> never using the documentation, I rarely think to copy little snippets
> to it. We do have the
> http://www.boltwire.com/index.php?p=solutions.snippets page, but it is
> woefully underdeveloped, and I don't think people are likely to use
> it. Still, is it better as solutions or as documentation?
>
> Vincent: Just about the time I am giving up BoltWire to keep looking
> for an "easy and flexible" software of this sort.
>
> Glad you are willing to give us a second chance. We have a small
> community, but a good one, and a growing one. Could you give me an
> example of two of what you found frustrating in learning BoltWire. Not
> only can we probably give you some help, but it would help me to
> identify the blind spots in our documentation. I have not tried
> everything out there by any means, but I do believe BoltWire is
> exceptional in a number of ways. After trying Drupal, Moodle, and
> PmWiki, I find BoltWire far faster, more flexible, and easier to use.
> It may just be my coding skills have increased, but I think it is the
> design architecture. If you stick with it, I don't think you will be
> disappointed. Give us a chance to help you get over the hump...
>
> Karl: 1. Beginners section which covers basic setup and configuration.
> 2. a Reference section which contains categories and Sub categories.
>
> I think this is exactly what we have. The start and handbook pages are
> just two sub sections of the doc area. Is the sidebar confusing? My
> thinking was having direct shortcuts to the start and handbook sub
> sections would be helpful. And that most users would eventually start
> going straight to the docs page for a full list of the
> topics/structure, and titles. I sense from the confusion here somehow
> this is not coming across too well. Can someone help me see what I'm
> missing?
>
> Thanks for everyone's input. It's great to see a community that cares
> enough to contribute to this software's development like this. We've
> come a long ways--thanks for urging us on to go even further.
>
> Cheers,
> Dan
>
>
>
>
> On Wed, May 20, 2009 at 10:07 PM, karlh626 <[email protected]> wrote:
> >
> > I was looking at the popup solution and found the tooltip solution.
> > This might be a better way to show examples.
> > >
> >
>
> >
>
--
Q-Mo
Wang-Chi Vincent Yeh
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"BoltWire" group.
To post to this group, send email to [email protected]
To unsubscribe from this group, send email to
[email protected]
For more options, visit this group at
http://groups.google.com/group/boltwire?hl=en
-~----------~----~----~----~------~----~------~--~---
