De-geeking BugReport on Wiki

Documentation General
#1

I have just de-geeked the BugReport page on the wiki, as well as a few
other updates.

Permalink:
https://wiki.documentfoundation.org/index.php?title=BugReport&oldid=63321

Diff:
https://wiki.documentfoundation.org/index.php?title=BugReport&diff=63321&oldid=62052

Full list of changes:

   - De-geeked parts of the page
   - Changed ALL CAPS (e.g. WRITER) to regular type (Writer)
   - Improved Ubuntu instructions on how to get to the terminal, as the
   Apps menu in Unity doesn't uses categories.
   - Changed some references to OO.o to OO.o and AOO
   - Added ADVANCED to the end of the "Extra info for developers" section
   header
   - Explained the Ctrl+Alt+T shortcut in some Linux distros for access to
   Terminal
   - Improved some English

#2

Hi Kieran,

I have just de-geeked the BugReport page on the wiki, as well as a few
other updates.

Thanks a lot for that, usually it's better to inform the QA team about
your work/modifications as this is their work that is detail here.

Permalink:
https://wiki.documentfoundation.org/index.php?title=BugReport&oldid=63321

Diff:
https://wiki.documentfoundation.org/index.php?title=BugReport&diff=63321&oldid=62052

Full list of changes:

   - De-geeked parts of the page
   - Changed ALL CAPS (e.g. WRITER) to regular type (Writer)
   - Improved Ubuntu instructions on how to get to the terminal, as the
   Apps menu in Unity doesn't uses categories.
   - Changed some references to OO.o to OO.o and AOO
   - Added ADVANCED to the end of the "Extra info for developers" section
   header
   - Explained the Ctrl+Alt+T shortcut in some Linux distros for access to
   Terminal
   - Improved some English

Something I do not agree with :

#3

The main reason I made those changes it because people who are reporting a
bug as a one-off need to be able to understand. Some people do not know
what "Bug Triager" means all they need to know is that "someone" on the LO
team will change it, and Urgent makes is a simpler phrase that "higher
priority".

I posted this to documentation as I was advised to do this by Tom D in an
off-list email, and also, it was listed in the _Documentation_ Wish-list
section.

Please reply if you have any more questions.

#4

Hi Kieran

The main reason I made those changes it because people who are reporting a
bug as a one-off need to be able to understand. Some people do not know
what "Bug Triager" means all they need to know is that "someone" on the LO
team will change it, and Urgent makes is a simpler phrase that "higher
priority".

Yes, but it's not exact and a bug triager is still not someone but a
volunteer of our project doing a hard work (do you call the butcher the
someone who cut the meet?), however, no matter.

I posted this to documentation as I was advised to do this by Tom D in an
off-list email, and also, it was listed in the _Documentation_ Wish-list
section.

Unfortunately sometimes Tom is not the good person for that, even if he
is really helpful elsewhere. The work of the QA project is concerned
here, so it's important that they are aware of what is done on their
pages. When you touch a category on the wiki that is not Documentation,
post also on the concerned list project (also the translators of the
pages will be aware that they have modifications to do).
BTW, off list messages on an open source project are never a good way to
work, we could have tell you about this before.

Please reply if you have any more questions.

No questions, only suggestions :slight_smile:

Kind regards
Sophie

#5

OK. Thanks for the suggestions and tips. I will take those into account the
next time I edit the Wiki.

Adding on the QA List so that they can see the changes I have made and
offer any corrections.

#6

Hi :slight_smile:
Sorry chap!  My understanding was that the page was for Users to read and be able to easily understand.  If that had been the case then obviously it would be smart for the Docs Team to have a look.  Other teams might be interested later but more as the general re-editing yo-yo before pages settle down with everyone reasonably happy about them.

I hadn't realised that it was really only a page for devs and other geeks and so NOT for users
Apols and regards from
Tom :slight_smile:

#7

Hi :slight_smile:
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.

Regards from
Tom :slight_smile:

#8

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:

#9

Hi :slight_smile:
wrt coloured backgrounds a pale yellow often helps some people with dyslexia.  So, i kinda like the simplicity of green for users, amber for more technical pages or internal pages such as minutes of meetings and then perhaps white writing on red for devs but i think it could easily get really bad visually.

Actually i like Sophie's point about the Documentation Team being responsible for wiki's in the documentation section and other teams being in charge of their's.  If we did go that route then everything aimed at normal users could be in the documentation section, preferably as sub-sub-sub-pages off the Published page.
Unfortunately that would mean moving a lot of pages.

Regards from
Tom :slight_smile:

#10

Hi :slight_smile:
wrt coloured backgrounds a pale yellow often helps some people with
dyslexia. So, i kinda like the simplicity of green for users, amber for
more technical pages or internal pages such as minutes of meetings and then
perhaps white writing on red for devs but i think it could easily get really
bad visually.

Fair enough. I was largely suggesting the background color to make it
easy for beginners to determine what content was written at their
level. Using some kind of header image or big icon in the sidebar
could work similarly.

Actually i like Sophie's point about the Documentation Team being
responsible for wiki's in the documentation section and other teams being in
charge of their's. If we did go that route then everything aimed at normal
users could be in the documentation section, preferably as sub-sub-sub-pages
off the Published page.
Unfortunately that would mean moving a lot of pages.

Hmm... are you suggesting that the Documentation Team would handle all
of the pages for beginners? Providing a consistent tone and authoring
style across all of the beginner pages could be beneficial, but could
give them a lot more work, especially in terms of keeping the beginner
docs up to date with information from upstream teams.

--R

#11

Hi :slight_smile:
I kinda like the look of the Bug Report page at the moment.  Users seem fine with it now.
Thanks and regards from
Tom :slight_smile:

Impressum (Legal Info) | Datenschutzerklärung (Privacy Policy)   Content on this site is licensed under a Creative Commons Attribution Share Alike 3.0 license.