[Libreoffice-qa] [libreoffice-documentation] De-geeking BugReport on Wiki

[Robinson Tryon]

"On Sat, Feb 16, 2013 at 1:22 AM, Tom Davies <tomdavies04 at yahoo.co.uk> wrote:
> Hi :)
> I like the changes.  Actually i prefer
> "someone" to "bug-triager"
> and
> "person" to "developer"
>
> While the more precise definitions are important to us and we might 'naturally' understand what the terms ,eam those things might not be so obvious to a noob.  In photography a developer is a liquid and bug-triager could be a bot or anything.  It could even mean that crazy loony from CSI: Vegas.  I think the important thing for a noob to know is that when they post a bug-report the very next actions that happen to the report will be done by a person, a human being, not a machine ior automated process.  Beyond that is just confusing detail that they don't really need to know at such an early stage.
>
>
> Perhaps some hierarchy tree or flow-chart might help the user understand the process that happens after filing the bug-report but again i think it's too much information and so it risks confusing the poor wide-eyed-end-user.
>

As Tom notes above, when we write or update documentation, we need to
think about our audience. It's really important that we think about
the most exposed pieces of our internal docs and make sure that they
are comprehensible to outsiders.

For example, here's a chunk of the current text on that page:

---
If you are not sure what component your problem is about, choose the
Libreoffice component. Someone will come and change it later. For more
information about this, have a look at "[[BugTriage]]". If it is an
urgent issue (broken parts, regression, etc), experienced users can
assign it to one of the developers listed on the [[FindTheExpert]]
page.
---

All of the information in the above paragraph is useful to someone,
and that's why it's there. Unfortunately, even though "someone"
(probably a Bug Triager) needs to know that information, most users
don't. That's why it would be good for us to have a much simpler page
targeted at users that provides the minimum amount of information they
need to submit a bug report.

At the top of that simple page, we could provide a big link that
points experienced users and volunteers to the Advanced Bug Report
Page. That split should make it easier for us to keep detailed
documentation in one place, and have very simple, derivative
documentation for our regular users.

In addition to making our docs as simple as possible, we need to make
bug submission as simple as possible. The BSA is a good start, but
there's a lot more we could do to simplify bug submission for ordinary
users. (But that's probably a topic for a different thread :-)

Cheers,
--R

P.S. Here's a quick thought: Would it be possible for us to put a very
light background tint on the wiki pages? We could color all of the
pages reviewed to contain content suitable for beginners with pale
green, and use other colors for particular content or technical level.
Default of white, of course. This could serve as a helpful clue for
users who are clicking around our site.