Re: Some ideas

[Shaun McCance <shaunm gnome org>]

Hi Gil,

Thanks for the input.  Thoughts below.

On Mon, 2009-08-10 at 00:15 +0200, Gil Forcada wrote:
> Hi,
> 
> First of all great job!!
> 
> Now that there are lots of ideas on improving, re-focusing and revamping
> the documentation I will put here some ideas that I had some time ago
> when I first heard of moving from descriptive to topic based
> documentation (great change!).
> 
> I don't know if it's the approach you want to take but shouldn't be
> useful to try to create skeletons of documentation (that is, what topics
> should be covered for each documentation) just as placeholders, make
> them as narrow or focused as possible and try to get as much skeletons
> as possible for say 3.0 and then start campaigning (a-la GHOP) to get
> more and more bodies coming to life :D

We just had a (very short notice) meeting earlier today, and
one of the things I brought up was identifying common content
types and setting up some templates and instructions for them.
We can identify content types like task, concept, tutorial,
tip, introduction, etc.

I think that's a big piece of what you're suggesting, although
what you're saying sounds like setting up "templates" for the
very organization of the document.  I think that's something
we should pursue, but we need to be careful about it.

We have these old templates we use for DocBook documents, and
one of the problems with them is that people just fill them
out without putting any thought into what information really
needs to be in the documentation.  We want to avoid a scenario
like this.

I'm not saying I think it's a bad idea.  I just think it's an
idea we need to approach carefully and do well, otherwise it
could backfire.

I think, for right now, we should work on content types for
individual pages.  And we can work on guidelines for document
organization as we get more experience.

> That way it would be easier to ask maintainers/power-users (which will
> be the ones that tries early versions of the softwares) what they think
> it could be useful to know (i.e. the bones) and then after the
> brainstorming having a nice way to contribute those muscles to make the
> bones filled (write the text on a bug-report, on the wiki, on the
> revamped website, inside Yelp itself and having a-la bug-buddy bugs
> filled, whatever).

I was just thinking the other day about having a web site
where people could write and submit help pages.  Since we
have Mallard, it should be possible for people to just
write about something without having to futz around with
document organization.  Obviously, we have to deal with
content organization to get the content in, but we should
be able to get people to write stand-alone topics much more
easily now.

And a basic web-based Mallard editor wouldn't be too hard.
It doesn't have to feature everything.  It just needs to be
good enough for somebody to write basic content.  We can
clean things up before they go into git.

So people would be able to go to this site, select a document,
and just write something and submit it.  And then that would
get sent to bugzilla, or maybe it would stay on that site.
At any rate, we'd have some means of looking for contributed
material and merging it or rejecting it.

Could be a really fun project for somebody.  I have way too
many projects on my plate right now as it is.

> Now, the other way around:
> 
> If the idea is to ask the users what they would expect instead of trying
> to guess (as it was on the previous idea) wouldn't be useful to use the
> new revamped GNOME website to have weekly/bi-weekly/monthly surveys
> (with advertisements on p.g.o, irc and wherever possible) on a specific
> topic/application to get feedback?

We did the Empathy survey, which was absolutely invaluable.
But one of the things that was noted about the results was
that we had a lot of responses from technical users.

We absolutely want to do more surveys in the future.  But
we need to figure out how to reach a less geeky audience.

Also,  maybe we should talk to the usability team to see
if we can cooperate on surveys.  So surveys help us to see
where users are getting confused, and this helps us shape
the help better.  Frequently, the things we need to write
about are things that could arguably just be better in the
application itself.

> Or maybe, even it would be useful to log what users are searching on
> Yelp and send it somewhere (I'm not taking care here of data gathered by
> the application) to process it. 

I've thought about this a few times, but I don't want to
phone home without explicit user permission.  Even if it's
guaranteed to be completely anonymous.  If I could just get
data on people's click paths, and maybe their search terms,
it could help immensely.

But when people come to Yelp, they're not interested in using
Yelp.  If I annoy them with a "can I send data?" dialog, I'm
seriously failing my target audience.  But if it's any less
intrusive (say, hidden in a menu), only the geekier part of
my audience is going to find and enable it.

It's a conundrum.  I'd love that data, but I can't think of
a way of getting it without introducing fail.

--
Shaun