Better help info for relating a resource to a focus

[boud]

hi dmitry, everyone,

On Fri, 25 Nov 2005, Dmitry Borodaenko wrote:

> On Tue, Sep 06, 2005 at 01:57:57AM +0200, boud wrote:
> > While people are thinking about the sanitize bug,

Hopefully i'll get back to this soon, but first i'd like to help 
with getting a good explanation going for the resource/focus issue.

i had a *lot* of trouble actually understanding this - so my guess
is that other people might also have problems.

Anyway, here goes...


> From the text in

http://savannah.nongnu.org/cgi-bin/viewcvs/samizdat/samizdat/doc/concepts.txt?rev=1.99

the basic idea is fairly clear.


However, i think the basic info on the two basic methods of linking 
is missing and/or confusing, sorry :P.

IMHO, the two basic actions a user would like to do are:

(1) link present resource to a resource which has the status of "focus"

(2) consider present resource to have the status of "focus", and link 
another resource to it.

Most of the time, it probably makes sense to encourage users to do (1)
rather than (2) - not every article is useful as a new node in the network.


Under the title "Related Focuses" under an article (e.g. 
http://belarus.indymedia.ru/1253), what i understand is that we 
have:
(a) a list of focuses that already have been related to this resource
(b) the presently active focus chosen by the user

(c) a suggestion to do (2), but with insufficient and confusing information
(at least in English)



IMHO it is clear in (a) and (b) from the popup, that (1) is possible.


However, what is missing is:

FAQ-(1.1) (a)+(b) 
The user thinks, "Hey, i want to find the most useful, logical focus 
to which to attach this resource to, but i don't see how to find the other 
obvious focuses, such as Ecology, Women's Rights, Education, ... - i only 
have the choice of what other users (with whom i disagree!) have already
chosen. i want to link this article to (e.g.) Women's Rights, not Education!
How do i do this?"

FAQ-(2.1) (c)
The user thinks, "Hey, i want to make this into a focus
and relate other resources to it - as the popup tells me i can do. How do
i do this?"


FAQ-(1.1)-PROBLEM:
 The user wants to link this resource to some focus that others have
not yet thought of. Now, suppose the user looks around for help, and
reads the popup for (c), which tells the user that s/he can focus on
this article itself as something useful to do. Naively (like me :P),
s/he tries this.

What is the result? Now (b) is an offer (which in fact is an offer 
to link the resource to itself) with the word "vote".

It is the only thing that seems to have changed, so the user concludes
that it is probably the next step.  S/he clicks, and is told that linking
a resource to itself is useless.

Problem summary: what looks like help information is information for a
different task, and the necessary help information is lacking.



FAQ-(1.1)-POSSIBLE-SOLUTION:

IMHO we need some information, preferably with a link *before* the user
starts reading (c). E.g., between (b) and (c), something like:


"To relate this resource to a focus not listed here, (1) find and go to the
focus you believe is important, e.g. <a href="/foci.rb">list of foci</a>,
(2) make that focus your selected focus, and then come back to 
this resource, to this section on Related Focuses. 
Your selected focus will then be listed above this paragraph and you
can make the connection."



FAQ-(2.1)-PROBLEM
 The user wants to link *another* resource to this one, treating this
one as a focus. Well, nearly the same problem as for FAQ-(1.1)-PROBLEM.

The user looks around for help, and reads the popup for (c), which
tells the user that it is enough that s/he focus on this article, and
then it should be obvious what to do next.

The user does this. Now (b) is an offer (which in fact is an offer 
to link the resource to itself) with the word "vote".

It is the only thing that seems to have changed. The user tries this
and discovers that this is useless :(.

How does the user now link the *other* resource, which s/he wishes to
link to *this* resource, which has now become a focus?

The reader notes that (c) says something like "Focus on this resource".

S/he thinks: oh dear, this did not work. This article (or whatever) 
is *still* considered to be a "resource", it is not yet a "focus". 
How do i make it into a focus?


Problem summary: the help information for the required task says nothing
about the need for a second step, and the feedback after the first step
suggests that the first step has failed.


FAQ-(2.1)-POSSIBLE-SOLUTION:

2.1.1. Replace:

"To vote on how other resources are related to this one, focus on it."

by

"To vote on how another resource is related to this one, first focus on it,
then go to the other resource."

2.1.2
Change the code for what is printed under "Related Focuses" so that
if the present resource is the selected focus, then

"Focus on this resource (<title of resource>)"

is omitted (not printed).



i also added an English explanation to

http://belarus.indymedia.ru/1253

The html is below. My feeling is that stuff like this (and especially this)
should become part of the basic package.


pozdr
boud





<p>The Samizdat software implements the principle of "open moderation"
(Open Editing) for creating the structure of the site. This means
that this process is open for all participants in the project, and
everyone with internet access can observe the process.</p>

<p>The entire structure rests on the connection between the messages
(resources) and the themes (foci), to which these messages relate. Any
participant in the site (registered user), by means of open voting,
can create such connections, though the software also makes it
technically possible to limit access to voting only by the fixed list
of moderators.</p>

<p>A connection is created as follows.

<ul>
<li><strong>The first step:</strong>
 <strong>choose a theme</strong>, called a <strong>"focus",</strong> 
to which you wish to link a message (<strong>"resource"</strong>).
This can be either an already existing theme (focus) or it can be 
any already existing message (resource), which will gain the status
of a theme (focus) after the connection has been made.<br />

For a new theme (focus), it is best to choose a message whose title 
clearly represents that theme, and whose text describes the essence of
the theme (if it is not obvious from the name).

<li><strong>Go to the message (resource)</strong> which represents the theme 
you want,
and scroll down to the section <i>"Related Focuses"</i>, located below
the text of the message. You will find
text something like <strong>"Focus on this resource"</strong>
or <strong>"to select this resource as the current focus"</strong>.
(This text is present only if the user has a right to connect resources
to foci). <strong>Click on that text</strong> in order that your chosen
theme (focus) becomes the active (selected) focus.

<li><strong>The second step:</strong>
<strong>go to the message (resource)</strong> which you wish to connect to the 
theme (focus).
Scroll down to the section <i>"Related Focuses".</i>


<li>Now you should find your previously selected theme (focus) listed 
as one of the related focuses. If you are authorised to "vote", you can
then <strong>click on vote</strong> and then choose the degree to which you 
consider the resource to be related
to the focus.

<li><strong>Third step</strong>. The votes range from -2 to +2. The vote of 
each individual
user is stored separately and can be changed subsequently. The collective
estimate of the connection strength is defined as the arithmetic mean of all votes. 
<strong>Choose your vote from -2 to +2</strong> and then <strong>click on 
submit</strong> to make the connection.

</ul>
</p>

<p>If the collective estimate of the connection strength is more than 0, 
then the message (resource) is linked to the theme (focus) and is listed
on the page of that theme, sorted according by publication date.
</p>

<p>If the collective estimate of the connection strength is greater than
the threshold value for "theme messages" (by default a value of 1.5), 
then this message is also included on the main page in the theme column,
sorted according to the date/time of when it was first linked to this theme.
</p>