I really like the focus on the users point of view, particularly the new ones. Imo it helps to view the project with "fresh eyes". As an user myself, even if since 2005, I must admit sometimes I have difficulties to understand the decision making flow and what are the decisions themselves. But sure, the communication effort is evident. Even in my experience software.opensuse.org is often little-known, a pity, it's really useful particularly after the redesign (thumbnails, unsupported sources hidden by default, etc.). Really worried about the documentation area as a whole, and the wiki particularly. It's really difficult to find what you search for if you don't know your way. Caig -- To unsubscribe, e-mail: opensuse-project+unsubscribe@opensuse.org To contact the owner, email: opensuse-project+owner@opensuse.org

On 2014-04-08 23:30, Jim Henderson wrote:

Modern thinking about documentation is very different than the traditional "installation guide/reference guide" sort of stuff.

Most users don't want to read a user guide from cover to cover these days - they want help for the task at hand, rather than to try to absorb a firehose of information all at once from a guide and then to try to apply it to a live system. ... that they're not helping populate a knowledge base. They just want their question answered, regardless of who has to spend time answering the same questions multiple times.

But the people answering those questions do need the documentation, and read it at some time ;-) -- Cheers / Saludos, Carlos E. R. (from 13.1 x86_64 "Bottle" at Telcontar)

On 2014-04-09 00:45, Jim Henderson wrote:

On Wed, 09 Apr 2014 00:30:01 +0200, Carlos E. R. wrote:

...

But the people answering those questions do need the documentation, and read it at some time ;-)

Well, that's the hope, but usually knowledge like that is "tribal knowledge" rather than learned from a book.

Nah, how else could we have the joy of telling them to RTFM? :-PP (joking!) -- Cheers / Saludos, Carlos E. R. (from 13.1 x86_64 "Bottle" at Telcontar)

On Wed, 09 Apr 2014 16:36:25 +1000, Basil Chupin wrote:

On 09/04/14 07:30, Jim Henderson wrote:

...

On Mon, 31 Mar 2014 20:00:18 +0200, Caig wrote:

...

Really worried about the documentation area as a whole, and the wiki particularly. It's really difficult to find what you search for if you don't know your way. Modern thinking about documentation is very different than the traditional "installation guide/reference guide" sort of stuff.

Most users don't want to read a user guide from cover to cover these days - they want help for the task at hand, rather than to try to absorb a firehose of information all at once from a guide and then to try to apply it to a live system.

[pruned]

Wrong! :-)

You are not listening.

You are proffering *your* ideas on what *you* believe people *should* be doing - or what should occur for *you* to find it more convenient for yourself :-) .

If I were looking for something more convenient for me, I'd be doing away with the documentation entirely because I don't find I need it (other than the occasional man page). What I'm describing is an industry trend. I actually /do/ write technical documentation for a living, so I watch the trends and see what users and customers do and desire. They don't want something that describes that a password field is "where you enter a password". That type of descriptive documentation is, by and large, entirely useless to users, because the UI tells them that that's the value that goes in the field.

The above was from a FWD post which is telling everyone what the people at the "receiving end" - "the sharp end of the stick" - are feeling, thinking, expressing, and wanting.

Yes, and I understand that entirely. I see what you're trying to do, and quite honestly, if you have something to say to me, I wish you'd say it in a constructive way rather than trying to "make a point" by doing this. It's not helpful nor does it particularly add to this discussion.

I have read some parts of the openSUSE "wiki" when looking for information and I find it to be semi-literate in nature, too small in print, and "all over the place" when trying to find information. And is ancient history, not current to what is "now".

Yes, I agree. That's one of the downsides of OSS development - you tend not to have professional writers writing documentation, and in general coders tend to want to write code rather than documentation - so good documentation can be very hard to come by unless the project (whichever project it is) makes documentation a priority and gives it specific attention.

(And, of course, now I will be asked to provide examples of what "is ancient history" - sigh :-( .)

If you want to see what I consider to be most helpful documentation on a Linux distribution have a look at the ones for Ubuntu:

https://help.ubuntu.com/community

and especially:

https://launchpad.net/

Both clearly set-out, in easy to read font.

Because Ubuntu caters to new users, and apparently has made documenting things in a way that's digestable for new users a priority. That doesn't mean, though, that users will tend to dig into a documentation set rather than, for example, visit the Ubuntu forums and ask a question, even if it's covered in the documentation and even if it's easy to find. The trend (and I'm not saying /every/ user does this, that's not a 'trend') is that the user goes for what is most convenient for them - to ask a question and wait to be told the specific answer they need rather than have to even search for it. The only way to effectively combat that behaviour is to make the information more conveniently available than even asking a question. Jim -- Jim Henderson Please keep on-topic replies on the list so everyone benefits -- To unsubscribe, e-mail: opensuse-project+unsubscribe@opensuse.org To contact the owner, email: opensuse-project+owner@opensuse.org

On Fri, 11 Apr 2014 21:30:31 +0200, Caig wrote:

2014-04-09 18:09 GMT+02:00 Jim Henderson :

...

I see too the many users requesting over and over the same questions. More difficult is to see how many users just find by themselves the answers they need.

Practically impossible, really, because while you might have page hits, you don't know what they were looking for, or if they found the answer on the specific page they visited.

Probably some of them use the wiki (or try to do so), if the statistics available here http://en.opensuse.org/Special:Statistics are reliable, in the last 24h (20:00 - 20:00 CET) the English wiki received ~50937 visits (I save the data since some times). At least a fraction should be real users.

Sure, you'll always have some robots that are indexing or scraping the site.

There will be always the "lazy" users, but a more user-oriented* wiki could be useful at least for the rest (even to give a link to the lazy ones :P).

In a little over 20 years of doing online support, I can say that while there always have been lazy users who have just asked rather than doing some research first, this trend has increased from what I've seen. What's more, it's exacerbated by the fact that many users don't provide enough information (some because they don't know what to provide, even in terms of basic information - like DE or oS version), so it takes several exchanges to get the information needed to make a proper diagnosis. Many just don't know how to ask effective questions, so we get the functional equivalent of "my thing's broke." Often times, users with some experience will actually try to include useful information, but often times will only guess about the problem rather than describing what they're actually seeing (or including actual screen output). "I get an error message" is far too common, without either context or the actual text of the error message.

Wiki context-reachability (from YaST for example) probably it's too difficult/not doable.

* For example (borrowing ideas from the first thread message): - right-to-the-point guide (the SDB...the potentially more useful namespace currently hidden by the search default settings...) - easier instructions (GUI way) in the first place and then, if really needed, the more cryptic ones for the geeks (that probably don't need them...)

I think, perhaps, what we need to do is put together some sort of "new user survey" to find out the sorts of things new users find they need to know or would like to learn about. We know, for example, that installation of multimedia codecs is something we see a lot of requests for help for, and as most of us are very seasoned at adding the Packman repo and switching the packages over to that repo (installing whatever it is we need from there when relevant), it's not as clear-cut to a new user as it is for the experienced user. But what we need to identify is what leads a new user to ask (for example) on Facebook rather than the forums (or to even read the sticky that explains multimedia to them) or to go to the wiki. Jim -- Jim Henderson Please keep on-topic replies on the list so everyone benefits -- To unsubscribe, e-mail: opensuse-project+unsubscribe@opensuse.org To contact the owner, email: opensuse-project+owner@opensuse.org

On Fri, 11 Apr 2014 23:12:10 +0200, jdd wrote:

Le 11/04/2014 21:30, Caig a écrit :

...

There will be always the "lazy" users, but a more user-oriented* wiki could be useful at least for the rest

I think it's the way choosen some time (years?) ago, and it's a wrong way.

wiki are searched by google or it's own search engine, and admins have to focus on this.

then wiki are *written* by volunteers that can't know the desired structure and shouldn't have to worry about. I stopped writing on the wiki when it became necessary to organize it.

"wiki organization" is contradictory by essence. just now the forum archives do the job of the wiki.

It's perfectly nice to have a *documentation* web site, different from the wiki and well organized, but this have to be done by a documentation staff, not by random user - I think something similar is on the way for openSUSE

I somewhat agree and somewhat disagree. I've always thought that a wiki could be structured, but the structuring needs to be handled by a dedicated team, with the content provided by volunteers. But the volunteers need to have some input into the structure, too. There's a strong need for a "team" to write like this. Structure, though, is a high-level idea in a structured wiki. I've seen them successfully implemented using twiki, for example, and I think something like that could work for us here. The Povray project uses a structured wiki for its documentation, in fact (they use Mediawiki - I initially helped them set it up for that purpose). There are some special tags they use so the wiki forms the basis for a single-sourced documentation set. It actually works pretty well. Jim -- Jim Henderson Please keep on-topic replies on the list so everyone benefits -- To unsubscribe, e-mail: opensuse-project+unsubscribe@opensuse.org To contact the owner, email: opensuse-project+owner@opensuse.org

On Sun, 13 Apr 2014 17:27:28 +0200, Caig wrote:

...

I think, perhaps, what we need to do is put together some sort of "new user survey" to find out the sorts of things new users find they need to know or would like to learn about.

I really like the idea: focus on the users (and potentially new contributors, the future of the project)

Well, ideally most of the documentation that's on the website should be targeted at new users, I think. The focus for new contributors is somewhat different, depending on the nature of the contribution they want to make.

+1 writing/updating pages (even a single one a single time) and keeping all the wiki structured (or grouped if structured sounds heavy/too limiting) are two different tasks. Even to avoid duplication of effort like these for example - http://en.opensuse.org/SDB:LAMP_setup and http://en.opensuse.org/SDB:Linux_Apache_MySQL_PHP - http://en.opensuse.org/SDB:Apper and http://en.opensuse.org/SDB:Apper_troubleshooting or poor orphans barely discoverable http://en.opensuse.org/Special:LonelyPages

Exactly - that's why structure is needed - you end up with duplication, and with duplication, you have the serious potential for multiple conflicting ways to handle things. While there may be multiple ways to do things, for new users particularly, the simplest way to get things going is with the simplest procedure. Understanding the interdependencies between different parts of a knowledge domain is also important in order to build a flow. Even if a user starts with implementing LAMP, they might need some prerequisite knowledge on Apache, MySQL, or PHP. If there aren't references like that, then users end up frustrated because they'll read an instruction and say "but I don't know how to do that - where do I go look?" and they can't find it. Jim -- Jim Henderson Please keep on-topic replies on the list so everyone benefits -- To unsubscribe, e-mail: opensuse-project+unsubscribe@opensuse.org To contact the owner, email: opensuse-project+owner@opensuse.org

On Sun, 13 Apr 2014 21:21:15 +0100, Administrator wrote:

On Sun, 2014-04-13 at 18:33 +0000, Jim Henderson wrote:

...

...

...

I think, perhaps, what we need to do is put together some sort of "new user survey" to find out the sorts of things new users find they need to know or would like to learn about.

I really like the idea: focus on the users (and potentially new contributors, the future of the project) There is an existing survey: the search terms used on the opensuse site. Most opensuse users, I imagine, go there first when they need information.

You might be surprised. But while I agree that that's valuable data, that's not really a "survey". Surveys have more structure to them than just raw data.

After that you could try the most popular google search phrases including the word opensuse.

After having read the search terms that land people at various websites (some blogs even post them periodically), I'm not sure that that would be quite as useful. For example, read the "Road to Popehat" posts at popehat.com. :) Jim -- Jim Henderson Please keep on-topic replies on the list so everyone benefits -- To unsubscribe, e-mail: opensuse-project+unsubscribe@opensuse.org To contact the owner, email: opensuse-project+owner@opensuse.org

On Tue, 15 Apr 2014 22:16:45 +0200, Caig wrote:

yes, i explained badly the thought (language doesn't help). I just think the focus on the users ( on their point of view, I believe this is the general meaning of the hawake's first message) can help to engage them. And potentially some of them will give back the attention to the project as contributors.

That's certainly true - and a beneficial side-effect. :) Jim -- Jim Henderson Please keep on-topic replies on the list so everyone benefits -- To unsubscribe, e-mail: opensuse-project+unsubscribe@opensuse.org To contact the owner, email: opensuse-project+owner@opensuse.org