Author Coffeeshop

Posted by Gary Cunningham-Lee Wed 18 Apr, 2007 13:13 GMT-0000 posts: 36 ☆ ☆ ☆ ☆

This is a reply I wrote for the dev ml, but taking xavi's suggestion, I'm putting it here instead.

First, this is from IRC today. The main idea discussed with luci is to have draft pages at tw.o and the final versions at doc.tw.o., for your consideration:

Earlier, I talked with dthacker and these were my main points:
- The priority should be on keeping doc pages clear and easy to use.
- Discussion should be elsewhere.
- "Metadata" like editor-talk and under-construction type things should
be kept off the page or minimized.
- User feedback/comments/additions shouldn't go directly on the page in
a way that makes the main content harder to see and understand.

(In an email) Michael Pilling wrote:
> ....
> Currently we are sometimes operating as if there was no rational plan
> for segregating the function of two and doc.two. (and dev.two)
> Initially i was strongly thinking that a separate doc.two was a big
> waste of time and effort. Marc convinced me that there were good
> technical and strategic reasons to maintain a separation. But clearly
> this is an either/or situation. having docs being written in two
> different places with two different navigation structures and rulesets
> is just nuts - it doesn't benefit anybody.

I think that may depend on how it's organized. If there's a clear
delineation of purpose, then I think using both sites would probably
work OK. To me, it doesn't necessarily matter if the draft pages are on
one server or the other, but I think it's good to keep the final pages
looking "final" and yet have a way for people to comment and make changes.

There's also luci's point that splitting the functions to two domains
gives us a pretty usable mirror to cover any downtime.

>
> My guess is that this is just a team communication issue. No formal
> plan exists (to my knowledge) and people just do whatever they are
> used to doing.

I think the idea of separating all the doc info to doc.tw.o is good
conceptually and this also lightens the tw.o server load, but things
could also be organized with a different conceptual dividing line:
doc.tw.o is read-only, in a sense, for the final versions, tw.o is
everybody-editable, for the drafts. This is consistent with the general
tw.o editing policy. Either way makes sense to me.

>>> ....
> We want to have a PDF. Agreed.
> PDF's are created via structures, so structures must exist, but when and how?
>
> Unless somebody pays attention, structures become static and won't
> evolve with the documentation. It is an additional layer of management
> when we are very short on resources.

By "structures" here do you mean Tiki's wiki structures? To me they work
well for organizing/navigating the doc pages, and I think it makes sense
to take advantage of this tool. I guess I'm assuming that somebody will
pay attention, so I'll help on that. I

> Right now there are many pages in the structure that are just blank
> pages, while decent documentation exists, just on another page with a
> different name. We shouldn't force documentation authors to know and
> follow that structure. They just have to link keywords - hubs and
> interconnecting spokes - its easy, its organic, and intuitive.

Isn't the structure just the "table of contents" of the documentation?
Whether a page itself or the structure placeholder comes first may not
matter so much; in either case, the result should be a good organization
of the material. If the structure doesn't represent the "hubs and
spokes" correctly, then it needs to be fixed. If there is a structure
link that points to a placeholder, then the problem is that the page
doesn't exist. If there are suitable pages but they were given
different names by the authors, then maybe they need to be renamed to
fit the structure. This assumes an appropriate top-down view of the
documentation, but I think that's reasonable. New info/pages not already
in the structure can be added pretty easily. If an author wants to add
an entry that doesn't already exist in the structure, there should be an
easy way for that to happen, of course. I think what having a
pre-existing structure does is set an overall framework for the
documentation, which to me seems like a better approach than something
generated bottom-up, for the whole thing to seem logical to a new user.

>
> (We have to decide and enforce naming conventions of course, which you
> and i have started to document, which is an important step forward.)
>
> I was thinking that when a new version is launched, someone could
> spend a day (or two or three) rebuilding a structure (which is mostly
> a copy of the old one) adapting it to changes and additions in the
> documentation. once this "snapshot" structure is complete, and the pdf
> is created, the structure can be put away, and not be the main table
> of contents (this is the essence of my concern with structures)

To me this is adds complexity to the process. Why not just compare the
in-place structure to the new Tiki release and see if the structure
needs to be modified? Almost all of it will be the same, for most
releases. It will be easier and faster to make the changes than to
recreate it from where it was put away, I think.

Ideally, assuming the documentation is up-to-date with the release, then
a pdf snapshot can be made, with that release number.

>> ....
>>> rightnow we are trying to force documentation to develop according to
>>> some predetermined plan that very few understand (and are too busy to
>>> administer) - the "mess o broken links" is created because the casual
>>> user ignores the structure and goes straight for the keyword search.
>
> by your lack of comment i think we are in agreement here right? -
> keyword driven page names, which mirror the actual words, phrases,
> filenames titles and errors they see as tiki users and admins is the
> way to go. People want to know how to install tiki, not
> TikiInstall right?

I suspect keywords for page names might not be sufficient since the
logical keyword for a page might be also used in other contexts, so
maybe context + keyword is necessary. I'm not looking at the docs pages
now, but I'd like to think the current page names are something like
that. (For sure "TikiInstall" isn't so good, with the redundancy of
"Tiki" there.)

>>>> Categories?: if everybody knows and uses the tag convention, they
>>>> could dissapear, I guess...

I have some homework to do here; is there some documentation on whatever
you are using along these lines?

>>>> IRC, should stay as it is, I guess.
>>> I agree, except that developers should stop answering support
>>> questions in what is a pretty ephemeral medium. They should step off
>>> irc and edit wiki instead. Most non-developers (end users) don't need
>>> the hassle of IRC anyway.
>> Once again, I want the devs to write code, and help me document that code. I
>> disagree with forcing their behavior. Tiki does not have a SABDFL.
>
> If developers answer a question on IRC, (or a listserve for that
> matter), they (someone) will have to answer that same question again a
> month later. and a month later after that. Result: they have less time
> to code.

I think the different ways to get info complement each other. IRC has
the immediacy; doc pages are always there and searchable; forums are in
between. They're all useful.

> People asking questions on irc can be effective if (and only if) that
> person transports the answer back to the wiki and puts it in the right
> place. - Unfortunately i don't expect that to happen at all.

Are the IRC logs archived somewhere? That'd be really good.

> Developers though do need to be in touch with the doc pages enough to
> verify that people are documenting their work correctly. placing their
> answers in the right place will serve their interests and virtually
> guarantee the success of the doc project. (users go where they are
> fed remember?)
>
> PS: I'm as intrinsically opposed to command and control as i am to
> futile direction less anarchy. My background is very much about
> facilitating grassroots communities. 😊
>
>>>
>>> users will go where they are "fed". If IRC is the only place where
>>> users are fed answers, no successful documentation will ever be
>>> developed.
>
> I stand by this observation. Its not quite true for tiki of course,
> but the principle is valid 😊

Although quite a few Tiki users don't seem to be familiar with IRC,
judging by comments in the forums, etc. So the "go where they are fed"
only applies to those who know how to get there. Others will starve or
change their diet. 😊

>>>> Forums? which ones: on doc.tw.o? or the doc. forum on tw.o? I would keep
>>>> just one, and use it for centralizing asynchornous discussion on do.
>>>> topics, not directly related to a single doc.
>>> I have been very anti-forum because i encounter so many support forums
>>> and find then all rather useless, because they don't refactor
>>> questions to use the right keywords which are the kernels of all
>>> solutions which exist (or not) in the KB.
>> I disagree, improve the channel of communication with the end user, not shut
>> it down. Do we need to improve the search? Add keywords to posts?

The forums are useful first of all for fairly quick help for the person
posting. I think the success rate is pretty high for the people asking
their question. How useful the forums are as an archive is debatable,
but I've done searches and gotten the information I was looking for
pretty often.

One thing that is a problem is that (anyway the last time I checked)
when a forum post turns up in a search, you can see that post, but it's
out of its context in the thread, and there's no way to find the rest of
the thread. I know from other forums it's often useful to see the
surrounding posts, and I wish Tiki's searches enabled this.

> Agree, but this is a problem of percention -
> A user who asks a question is not being well served. - They couldn't
> find the answer - our documentation has failed.

Sure, but people have different ways of attacking their problems, and
even with perfect docs there will be people who want to ask instead of
research/read.

Of course, it'd be great if more questions in forums could be answered
with a link to a doc page. (Sometimes I've thought if I put into doing
doc pages all the time I've spent answering tw.o forum questions, the
docs would be complete already and the doc workers would be sitting
around waiting for new 1.10 features to write about. 😉 )

> It mirrors the old parable about the man who saw many children
> drowning in the river, and was frantically trying to pull them all out
> and recruiting the whole village to help him.
>
> A monk comes upon this frantic scene and suddenly walks away. The
> villager shouts "father, how can you just walk away"
>
> The monk says, "you people are having trouble rescuing all the
> children in the river, so i will walk upstream and find the man who is
> throwing them in."
>
> I'm saying we should be encouraging developers (and users) to head
> upstream to where the problem of bad documentation can be fixed.
>
> - SNIP -
>
>>>>> I think the structure problem can be overcome by our continued
>>>>> successful collaboration. I'll continue to keep your quest for
>>>>> simplicity as one of my goals, and ask that you keep my desire to keep
>>>>> the help topic-base as one of yours.
>
> Agreed, I'm quite sure will continue to collaborate successfully. (its
> is working so far i think?)
>
> Others should join our little party in the editorial board for
> doc.two - in fact this must be our april meeting via email.

I'll try to get involved there.
>
>>>>> Dave
>
> Dave, thank you for taking the time to make a lively discussion of
> this. I have a fondness of bold proposals but I do defer to your
> experience, and hope you will continue to act as the non-SA BD for
> doc.tikiwiki.org.
>
> MLP