Help system
Lino
feel a bit stupid. Or as using swiss army knife only for knocking on
door.
The help system should include more "dumb user" oriented explanations
or even two different help trees, one for devs and other for users who
refuses to look under the hood. In both cases examples of use are
missing.
Also, solutions should include help.solution.name and
devhelp.solution.name pages, written propely, the same as istalation
help - step by step.
It is hughe job and not ment for one man, so I offer my help.
B.r.
Lino
Linly
my memory.
Dan has revised the whole docs structure recently. It's definitely a
hard work. IMHO, maybe we need to consider a more easy-to-contribute-
wiki-environment which can honor the contributors and allowing other's
help to improve the page.
For the help for beginners. I have two concerns:
1) I need big picture for explanations but I also need "real" examples
to show how to write a working code;
2) I need a purpose-oriented beginner's guide. The point is "if you
want to do this, you can use this, this, and this...and do it this
way..." Dan has written a nice tutorial on how to built blog using
BoltWire. It's a good example.
http://boltwire.com/index.php?p=docs.extend.create_bf
But in http://boltwire.com/index.php?p=docs page, it's difficult to
find out.
Oh, I think there could be a out-of-date button allowing contributors
suggest not-yet-updated-pages or plugins. So the page can be tagged
with a notice of "out-of-date" info and other users could be benefit
from this notice and contributors can generate a list to find where to
improve or update.
Cheers,
linly
jacmgr
> IMHO, maybe we need to consider a more easy-to-contribute-
> wiki-environment which can honor the contributors and allowing other's
> help to improve the page.
>
fast and help pages get re-oriented. I would suggest that a seperate
wiki be set up that can serve as a draft wiki site seperate from the
main BW Site. If good stuff comes up on the draft wiki site, then
Dan can move it onto the main bw site. Just let it grow like a wiki,
it may become self-organizing if members are allowed to "tag" pages
and create their own table of contents pages etc..., Then we can see
how each other understands boltwire. Dan can just sit and watch it
grow, as we fill it in. He can concentrate on code and keeping the
main BW wiki clean and functioning.
For beginners and myself, I just re-read these sections today and they
are most useful. The concepts section, read beginning to end, really
makes sense after using and playing with boltwire for a little bit.
http://www.boltwire.com/index.php?p=docs.start
http://www.boltwire.com/index.php?p=docs.concepts
The Editor
respond to a few of them:
1) Having special help* and devhelp* pages. This is a great idea.
Marcos suggested something similar awhile back and I missed it till
reviewing some old emails. Since then I've been chewing on it. But for
the time being I'm more inclined to try and build up our current doc
pages. And plugins help should go in the plugins page, generally. I
fear if we start dividing our knowledge base into help, devehelp, doc
& plugin pages, etc we'll have a harder time finding what we want.
2) More how-to tutorials like the "create a blog" one. Good idea. I
would like to see the docs.extend hierarchy, well extended, to include
many more such topics. I think it would be a great help. Can anyone
think of some examples of titles you'ld like to see there? Better yet,
anyone willing to write some?
3) An out-of-date button to quickly tag pages. This is a rather
practical idea. I'll be happy to write something up when I get some
time. Perhaps even a notes or faq field where various kinds of
messages could go. Then a docs search list displaying all pages with
messages. Like "update me" or "what does this parameter do". Once the
docs are fixed, you delete the note.
4) An easier to contribute wiki environment. I'm not sure I like the
idea of a separate wiki environment for docs for the reasons above
(#1), but I'm perfectly willing to open things up on BoltWire. Right
now only those in the group @docs can edit pages, but anyone can join
that group upon request. I'm willing to open that open to anyone with
a member account. I have been hesitant so far as I don't really have
time to manage spam. But I notice almost none in the solutions area
which are member editable. We could try it awhile and see what
happens. I don't have a lot of experience with open wiki's. Mine are
all basically CMS's.
5) One idea not mentioned is a downloadable docs zip you can install
on your wiki or farm. It would create less dependence on the main
BoltWire site, but might also decrease contributions to the group
documentation... I'm not inclined to put all the docs in the core,.
Thanks John with the feedback on our current documentation. I
personally like the new organization and feel more comfortable with
it. The big thing is working towards improved thoroughness and
accuracy. Another problem is I personally almost never use the
documentation. I automatically revert right to the code and look there
when I have a question. Which is why I like the new incode "help"
system--everytime I find an answer I can jot a note right there in the
core. I realize these little snippets are not extensive, but I'm open
to adding additional brief, notes to the core at any time. Almost
every release now has a improvement or two to the help notes. Just
make your suggestion.
Let's keep this discussion going until we come up with some ideas. I
just opened the docs up to @member editing and will try and add an
"update me" field or button or something when I get some time...
Cheers,
Dan
jacmgr
One argument for the seperate USER Wiki, is that many of us feel that
what we write may not be "worthy" or is not good enough for the main
boltwire site. I for one am hesitant to put something on the official
boltwire site, becuase:
1) I only partially understand what I am writing.
2) It may already be in the BW docs, and I don't know where it is.
3) I think someone else has better ways of doing things than my idea,
so I don't write my idea.
The second reason is that a WIKI and NOT A CMS, really grow
differently. The wiki should become self organizing over time. A CMS
you kind of have to set up the structure of the content beforehand and
contributors have to try to figure it out. A Wiki is encourages you
just to write. This is useful when the structure isn;t actually
known. I think each of us has a different idea of how the
documentation/help should be structured; but we all want the same
contents. A lot of the content is on the BW site already, but not
where I expect to find it. And, someone else wants the same content,
but they expect to find it in a place different from where I expect!
The wiki pages need to be able to be tagged for a category, and
include a comment/response area, and I think that is enough to get it
going.
Just my vote, set up a wiki, see what comes of it. Anything good
that comes out of it, you migrate those good sections to the main BW
site. If nothing good comes of it, then we tried.
As for tutorials:
I think what BW is missing, is not the tutorial, but a "guaranteed to
work first time" examples, for a standard BLOG, and a one page
complicated form (different fields, required fields, validation, and
field calcs) that logs its data and reports on the data. My issues
have been that the downloaded app doesn't work out of the box. If
these apps worked guaranteed, and then there was a DRAFT NOT-OFFICIAL
DOCUMENTATION wiki page, I think folks would jump in to provide
detailed documentation. That info could then be transformed intro an
official wiki page.
Martin
> I for one am hesitant to put something on the official
> boltwire site, becuase:
>
> 1) I only partially understand what I am writing.
> 2) It may already be in the BW docs, and I don't know where it is.
> 3) I think someone else has better ways of doing things than my idea,
> so I don't write my idea.
Make it as easy as you can for people to contribute.
Greetings, Martin
Linly
are "featured article", "Did you know..." entries shown on the front
page. It's the problem that so many pages hide in the wiki and you
don't know where to find, how to start, and which page needing
improvement.
So I suggest the BoltWire may consider some search (info) lists on the
main:
1) Most rated pages;
2) Update needed pages;
3) Most popular plugins;
4) ...
Cheers,
linly
The Editor
>
> I think we can learn from http://en.wikipedia.org/wiki/ where there
> are "featured article", "Did you know..." entries shown on the front
> page. It's the problem that so many pages hide in the wiki and you
> don't know where to find, how to start, and which page needing
> improvement.
>
> So I suggest the BoltWire may consider some search (info) lists on the
> main:
>
> 1) Most rated pages;
> 2) Update needed pages;
> 3) Most popular plugins;
> 4) ...
We have had a family emergency this week that has kept me occupied.
Which is why my posts have been less then frequent. But here are a
few thoughts.
1) I appreciate the hesitancy to edit the docs pages, but that may
just be a culture problem here, as the doc pages have been edit
protected except by special permission. Now they are editable by
anyone with an account. But I sense that needs to be combined with
efforts to change the culture. Somehow we need to encourage
contributions to the docs. I don't think realistically I will be able
to provide the documentation BoltWire deserves because I lack time,
and perhaps just as imortant, I don't use the docs. I read the code
when I get stuck. So our best bet will probably be to transform our
culture into something more open, and solicit contributions. However
imperfect they may be. They don't have to be polished or perfect.
Maybe some kind of syntax like:
<box>
Not sure about this but I think....
</box>
This might encourage people to suggest content when not comfortable.
Eventually these could be verified and added or deleted as needed.
2) To encourage development of the docs, I like the idea of some kind
of rating/flagging system. I propose we have a box at the bottom at
the bottom of each page with a simple check box to indicate whether or
not a user found the doc page useful, and second a text box to suggest
improvements to the page (with a few prompts, like questions not
answered, inaccuracies, ambiguities, etc). The first would just be a
running tally to give us some sense of the most helpful pages (just a
total of the number of yes clicks, perhaps converted to some kind of 5
star rating). The second would be used to generate a search list
called docs.help or something, which anyone could scan periodically,
then edit pages they feel they can fix, and delete the suggestion.
I'll try to get something up this week, but I'm finding myself short
on time these days... But I'll probably do something along these
lines. We could probably do the same things for the plugins as well.
Feedback?
Cheers,
Dan
Lino
L.
Linly
The wiki-culture is a long tern road.
Thanks Dan.
Cheers,
linly
On 2月18日, 下午11時04分, The Editor <edi...@fast.st> wrote:
> On Sun, Feb 15, 2009 at 9:55 PM, Linly <linly....@gmail.com> wrote:
>
> > I think we can learn fromhttp://en.wikipedia.org/wiki/where there