Need HELP texts for changed feature

Documentation General
#2

Hi :slight_smile:
I'm not sure where you need 'better' wording. It all looks good to me. It's
difficult to think of something that could be more elegant in the drop-down
box. The different options are very different lengths.

I think it is good to approach the docs team with stuff like this and hopefully
someone gets inspired. Btw i like replacing the tick-box with a drop-down to
allow more options.
Good luck and regards from
Tom :slight_smile:

From: André Schnabel <andre.schnabel@gmx.net>
To: documentation@global.libreoffice.org
Sent: Tue, 28 June, 2011 20:53:29
Subject: [libreoffice-documentation] Need HELP texts for changed feature

Hi,

I'm currently working on a fix for bug #30800.

The fix will include a minor change in the options dialog. What the
implementation will look like is documented at the wiki:

http://wiki.documentfoundation.org/User:Andreschnabel/Spec_Calc_grid_lines_on_colored_background
d

What I'm currently missing are the strings for the (product/wiki) Help.
I'm not a native english speaker, so id' prefer someone else could write
a short paragraph (for regular help) ans a two-liner (for enhanced tool
tip).

Thanks and regards,

André

PS.:
I would normally not expect a developer to come to the doc list an ask
for strings for such a small change. I'm just trying to find out, where
we can find people who contribute to a bugfix without being code
hackers. I'd like to see, what works and what not - and see how things
can be improved later.

--
Unsubscribe instructions: E-mail to documentation+help@global.libreoffice.org
Posting guidelines + more: http://wiki.documentfoundation.org/Netiquette
List archive: http://listarchives.libreoffice.org/global/documentation/
All messages sent to this list will be publicly archived and cannot be

deleted

#3

2011/6/28 André Schnabel <andre.schnabel@gmx.net>:

Hi,

I'm currently working on a fix for bug #30800.

The fix will include a minor change in the options dialog. Waht the
implementation will look like is documented at the wiki:

http://wiki.documentfoundation.org/User:Andreschnabel/Spec_Calc_grid_lines_on_colored_background

What I'm currently missing are the strings for the (product/wiki) Help.
I'm not a native english speaker, so id' prefere soemone els could write
a short paragraph (for regular help) ans a two-liner (for enhanced tool
tip).

Thanks and regards,

André

PS.:
I would normally not expect a developer to come to the doc list an ask
for strings for such a small change. I'm just trying to find out, where
we can find people who contribute to a bugfix without being code
hackers. I'd like to see, what works and what not - and see how things
can be improved later.

--
Unsubscribe instructions: E-mail to documentation+help@global.libreoffice.org
Posting guidelines + more: http://wiki.documentfoundation.org/Netiquette
List archive: http://listarchives.libreoffice.org/global/documentation/
All messages sent to this list will be publicly archived and cannot be deleted

--
David Nelson

#4

Hi,

I'm currently working on a fix for bug #30800.

The fix will include a minor change in the options dialog. Waht the
implementation will look like is documented at the wiki:

http://wiki.documentfoundation.org/User:Andreschnabel/Spec_Calc_grid_lines_on_colored_background

What I'm currently missing are the strings for the (product/wiki) Help.
I'm not a native english speaker, so id' prefere soemone els could write
a short paragraph (for regular help) ans a two-liner (for enhanced tool
tip).

I will be busy until 4 p.m. today but I will look at this as soon as I
get free, if no-one else has stepped in before then.

#5

Hi André,

I took a look at the wiki link and the discussion about this bug, and
realized it will take me more than 2 minutes to get into the context.
But I just received a mega-urgent client order that will take me all
evening to do, so I'll take a proper look at this during Thursday and
will provide the requested strings/help text (unless someone happens
to jump in before me).

So bookmarked until tomorrow.

#6

Hi David,

Hi André,

I took a look at the wiki link and the discussion about this bug, and
realized it will take me more than 2 minutes to get into the context.
But I just received a mega-urgent client order that will take me all
evening to do, so I'll take a proper look at this during Thursday and
will provide the requested strings/help text (unless someone happens
to jump in before me).

So bookmarked until tomorrow.

Thanks.

I'm going to send the code changes to the dev-list today. The help
strings can be done later - no problem.

This is open source .. release early, release often :wink:

André

#7

Hi André,

I'm going to send the code changes to the dev-list today. The help
strings can be done later - no problem.

Sure, OK, would you just like to post your proposed strings here so
that I can just take a quick look as regards grammar/spelling?

This is open source .. release early, release often :wink:

I understand, you bet. :slight_smile:

#8

Hi David,

Hi André,

I'm going to send the code changes to the dev-list today. The help
strings can be done later - no problem.

Sure, OK, would you just like to post your proposed strings here so
that I can just take a quick look as regards grammar/spelling?

UI strings are very short:

Text for text label: "~Grid lines" (same as for former checkbox)
Values for drop down:
   "Show"
   "Show on colored cells"
   "Hide"

For the Help I have currently no strings at all.

regards,

André

#9

Hi André,

UI strings are very short:

Text for text label: "~Grid lines" (same as for former checkbox)
Values for drop down:
  "Show"
  "Show on colored cells"
  "Hide"

Fine, they look good to me.

For the Help I have currently no strings at all.

Yep, I'll take a look tomorrow and will post back about this.

#10

Hi André,

I have been looking at the wiki page and I don't see clearly what you
might like to have in the help text.

May I suggest that you post a suggested text here, and then I'll check
it for spelling/grammar and ask any questions that might help ensure
clarity and ease of understanding?

#11

Hi :slight_smile:
That's what i thought. It's function seems so obvious and self-explanatory. I
think Andre is not subscribed to this list so it would help to CC him.
Regards from
Tom :slight_smile:

#12

Hi Tom,

I
think Andre is not subscribed to this list so it would help to CC him.

He's subscribed here, it's OK. Thanks. :wink:

#13

Hi,

Hi André,

I have been looking at the wiki page and I don't see clearly what you
might like to have in the help text.

Well .. neither do I :slight_smile:

May I suggest that you post a suggested text here, and then I'll check
it for spelling/grammar and ask any questions that might help ensure
clarity and ease of understanding?

Ok, will do.

This was more or less an experiment to see, how many people are willing
to help - and if these people already know how to help. First part of
the experiment is quite ok. But we need to improve on the second part.

Although there are lots of things in software development that need (and
should) not be done by developers (code-hackers), it seems, only those
developers currently know what these "things" are. I need to think a
while, what we can do to improve the situation.

Thanks and regards,

André

#14

Just proofed your bug report. Very well documented and complete.

How do new features get discovered by documentation writers?
By mining the wiki? Or is there a new feature list as things are being
corrected and added?

Richard.

#15

Hi,

> Hi André,
>
> I have been looking at the wiki page and I don't see clearly what you
> might like to have in the help text.

Well .. neither do I :slight_smile:

> May I suggest that you post a suggested text here, and then I'll check
> it for spelling/grammar and ask any questions that might help ensure
> clarity and ease of understanding?

Ok, will do.

This was more or less an experiment to see, how many people are willing
to help - and if these people already know how to help. First part of
the experiment is quite ok. But we need to improve on the second part.

Although there are lots of things in software development that need (and
should) not be done by developers (code-hackers), it seems, only those
developers currently know what these "things" are. I need to think a
while, what we can do to improve the situation.

Thanks and regards,

André

Hello André,

Just proofed your bug report. Very well documented and complete.

How do new features get discovered by documentation writers?
By mining the wiki? Or is there a new feature list as things are being
corrected and added?

Richard.

And maybe this is one way to ask for it. :slight_smile:

It just might fall through the cracks in the mailing list.

I suppose we need to review the wiki systematically.

#16

Hi,

Just proofed your bug report. Very well documented and complete.

Thanks.

How do new features get discovered by documentation writers?
By mining the wiki? Or is there a new feature list as things are being
corrected and added?

Currently developers collect development notes and write release notes,
blog about the implementation progress ...
So while there are some information around, this is currently not
satisfying for the people who need to know most of the new features.
This is not only documentation writers - these are also localizers,
quality assurance, people giving user support etc.

This was one of the reasons why I tried how a small specification can be
put to the wiki. Once more people use this approach,we could just add
categories (like NewIn3.5) and would have a good list.

But (i wrote this already at the design and at the German lists):
although I personally think, that a (basic and not over-formalized)
specification is welcome to most of the developers, hardly any developer
will write a detailed specification on his own. This is not because
developers are lazy - it is just that ~1/4th of the specification can be
written by non-developers. E.g.

- you do not need a developer to find the correct place for a new option,

- you do not need a developer to know what the new label should read,

- you do not need a developer to search in the OOo usage-tracking data
and identify how often a (supposed to be removed) UI item has been used.

- you do not need a developer to identify side-effects for the user's
workflow

- you do not need a developer to write the help

Some of these tasks even *should* not be done by developers, because
they (naturally) think more in terms of code (e.g. a developer's
decision where to put a new UI element might be heavily influnced by the
internal code structures - what is in many cases not the best for the
end user, not knowing the implementation). But the developer needs to be
involved, as she needs to give input about what works and what not (and
developers have ego's, so even their opinion about user interaction
should be considered :wink: ).

To give you an impression about the work that a non-developer could do:
I worked about 2 days on the spec (discussion at mailinglists, do some
mockups / prototyping, search for usage data, document what I found...).
The implementation was done in one and a half day - and it took only
that long, because I never ever did contribute new functionality to
LibreOffice before - during this one and a half day I learned how to
implement new UI elements and store options. I even did almost three
full implementations (the not used alternatives had been implemented for
learning purposes). After all - the real code-related work was less than
1/3rd of all the work.

We need to come to a point, where non-developers help with all these
things and collaborate with developers (code hackers). For this, we need
to make people aware (what I did was just a test of what people are
already aware).

regards,

André

#17

Hi,

May I suggest that you post a suggested text here, and then I'll check
it for spelling/grammar and ask any questions that might help ensure
clarity and ease of understanding?

Ok, will do.

And done - I found only two references tho the (current) option in our help.

1st: help for Tools - Options - Calc - View

Suggested text for the drop down:

Specifies how grid lines will be displayed. Default is to display grid
lines only on cells that do not have a background color. You may choose
to display grid lines also on cells with background color or hide them.
For printing, choose Format - Page - Sheet and mark the Grid check box.

(The second sentence is a copy from current help and is still correct.)

2nd: help on "Change Table Views"

"Under the menu item Tools - Options - %PRODUCTNAME Calc go to the View
tab page. Choose to hide Grid lines from the drop-down. Confirm with OK."

I just changed the current 2nd sentence "Unmark Grid lines."

btw.: This help item is incomplete, as we can hide grids per sheet view
toolbar.

3rd: Enhanced tooltip

Currently no enhanced tool tip is displayed for the checkbox as
respective help item has the wrong help-id.
It's easy to re-use halp text as suggested above, so I would use:

"Specifies how grid lines will be displayed. Default is to display grid
lines only on cells that do not have a background color. You may choose
to display grid lines also on cells with background color or hide them."

Strings with full xml-tags are at the wiki.

regards,

André

#18

Hi André,

just a few thoughts on certain aspects of this interesting-looking
subject...

Some of these tasks even *should* not be done by developers,

I'd suggest to change the wording here to a positive form, like...
  "Some of these tasks *should* be done by non-developers"

or even better avoid the negative form completely:
"... done by a mixed team of (advanced?) documenters/end-
users/designers/ux'ers/whatever ..."

...

We need to come to a point, where non-developers help with all these
things and collaborate with developers (code hackers).

(what I don't like here is the word "help", as it suggests "doing minor-
value work", so the problem or part of the problem might be the at least
somewhat "looking down" attitude of the developers?)

For this, we
need to make people aware (what I did was just a test of what people
are already aware).

I like the idea to "make aware" as a first step. However...

If you mean: "How to make implementing new features more attractive to
mixed teams instead of one-person-only?" then I think, this might be a
very sensible area as one of the major motivations of at least part of
the developers might be "to be the one who implements a feature". So
your question might be "who is willing to pioneer a mixed development
approach?"

Nino

#19

Hi,

Some of these tasks even *should* not be done by developers,

I'd suggest to change the wording here to a positive form, like...
  "Some of these tasks *should* be done by non-developers"

Well - I just some basic wisdom of software development - and it is
really about who should rather *not* do certain things. E.g. a developer
should not write a end-user documentation (or it will be missing lots of
things that are trivial for the developer but hardly known to an end-user).

or even better avoid the negative form completely:
"... done by a mixed team of (advanced?) documenters/end-
users/designers/ux'ers/whatever ..."

Yes - this is what it is meant do be finally.

...

We need to come to a point, where non-developers help with all these
things and collaborate with developers (code hackers).

(what I don't like here is the word "help", as it suggests "doing minor-
value work", so the problem or part of the problem might be the at least
somewhat "looking down" attitude of the developers?)

This is not at all "minor value work". There is of course the problem
that people tend to think that their own contribution is what really
matters - for developers this might not only be a tendency :wink:
But this is really tricky, beause if no non-developers contribute to new
feature implementation, you will very likely get a bad designed feature.
If no developers contribute to new feature implementation you will get
no feature at all.

So just convince developers to implement "real good features or the
users" instead of "implement cool features because we can". This can be
done best if you make them aware that also non-developers *do*
contribute a lot and ease developer's job. (Again - I don't want to say
that "help" has less value than "developer's job" here.)

I like the idea to "make aware" as a first step. However...

If you mean: "How to make implementing new features more attractive to
mixed teams instead of one-person-only?"

Hmm .. I don't think, thats the problem. My experiment showed, that it
is quite easy to have a "mixed team". For the spec I got input from
Astron at the design-list, I got valuable feedback from Regina at the
German list, I got hints for the code at IRC from moggi, bubli is
reviewing my patch. So, this actually is a mixed team - but mostly of
developers (people who already touched the source code).

It is really about awarness (what needs to be done for a good feature
implementation - and what can be done by non-developers and how can this
be done).

then I think, this might be a
very sensible area as one of the major motivations of at least part of
the developers might be "to be the one who implements a feature". So
your question might be "who is willing to pioneer a mixed development
approach?"

Oh - I'm actually doing this (at least I got the impression).

André

#20

Hi André,

I went to the wiki page and did a couple of small edits on the tool
tips there. I've replicated them here, too.

1st: help for Tools - Options - Calc - View

Suggested text for the drop down:

Specifies how grid lines will be displayed. Default is to display grid
lines only on cells that do not have a background color. You may choose
to display grid lines also on cells with background color or hide them.
For printing, choose Format - Page - Sheet and mark the Grid check box.

(The second sentence is a copy from current help and is still correct.)

I'd suggest a couple of minor changes:

"Specifies when grid lines will be displayed. Default is to display
grid lines only on cells that do not have a background color. You can
choose to also display grid lines on cells with background color, or
to hide them. For printing, choose Format - Page - Sheet and mark the
Grid check box."

2nd: help on "Change Table Views"

"Under the menu item Tools - Options - %PRODUCTNAME Calc go to the View
tab page. Choose to hide Grid lines from the drop-down. Confirm with OK."

I just changed the current 2nd sentence "Unmark Grid lines."

btw.: This help item is incomplete, as we can hide grids per sheet view
toolbar.

Can you write a suggested text here, so that we can review it?

3rd: Enhanced tooltip

Currently no enhanced tool tip is displayed for the checkbox as
respective help item has the wrong help-id.
It's easy to re-use halp text as suggested above, so I would use:

"Specifies how grid lines will be displayed. Default is to display grid
lines only on cells that do not have a background color. You may choose
to display grid lines also on cells with background color or hide them."

This one is in the wiki page, and I edited it there.

"Specifies when grid lines will be displayed. Default is to display
grid lines only on cells that do not have a background color. You can
choose to also display grid lines on cells with background color, or
to hide them."

HTH,

#21

Hi André,

I think the magic ingredient to getting non-devs involved in feature
implementations and bug fixes is to actively reach out to other teams
via the mailing lists when there's a specific need - like you did in
this case.

For instance, speaking for myself, I'm more than happy to help out.
All you need to do is buzz me with a specific request. The best way to
do that is to write to the list and ask for a volunteer. If I'm able
to oblige then I surely will. If I can't then maybe someone else will
speak up.

I can't think of a better way of doing things than this, but the
general initiative of involving non-devs in these things is good. It's
probably not always necessary, so outreaching on a case-by-case basis
is maybe the best solution?

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