Need HELP texts for changed feature

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?

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:

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:

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é

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.

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.

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é

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é

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

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é

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,

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?

Hi David,

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.

This won't work. As told in the other mail - it took twice the time to go to several mailing lists and ask for contributions than learning how to implement things and finally do the implementation.

If people want to change this situation we must do something - and we need to do more than telling developers to go to other mailing lists. I want to see more people at e.g. ux-advise list coming up with their own ideas an leading a work item (instead of just following the developer's suggestions).

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.

And I'm very thankfull for that.

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?

We should not be over-formalized with all this. It's really case-by-case.

But it is dangerous to have knowledge split across several mailing lists and non-developers not monitoring ongoing development. E.g., at some point I was in favour of removing the grid color option. The rationale was that there is an other place to define that color. Fortunately Regina made me aware, that we will face compatibility options with OOo.

regards,

André

Hi,

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."

Thanks - I'll use this.

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?

You may call me mulish - but there are dozends of documentation writers
here at the list, able to provide much better suggestions than I.
Everyone could do what I would have to do: Open product help, see where
the text is missing. Open calc and see what the other way is to hide the
gridlines. Write the sentence and file a bug report.

You may file the bugreport to me (I'll see, If I get direct commit
access for help files - well actually I even have that I think).

Imho documentation team should have the lead for product and online
help. Developers should only be involved for the commit to the source
repository.

Regards,

André

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.

This won't work. As told in the other mail - it took twice the time to go to
several mailing lists and ask for contributions than learning how to
implement things and finally do the implementation.

If people want to change this situation we must do something - and we need
to do more than telling developers to go to other mailing lists. I want to
see more people at e.g. ux-advise list coming up with their own ideas an
leading a work item (instead of just following the developer's suggestions).

Well, me, I'm signed up to the UX list. But it just makes another list
to track. Speaking for myself, I'm taken up right now working on
forging Alfresco into a useful tool for the project, so I don't
currently have a lot of time for other stuff, except when specifically
requested to do something.

Are we lacking some kind of software tool to help bring teams together?

Is it worth putting this subject on the agenda of an SC meeting and
talking about it voice there?

Hi André,

You may call me mulish - but there are dozends of documentation writers
here at the list, able to provide much better suggestions than I.
Everyone could do what I would have to do: Open product help, see where
the text is missing. Open calc and see what the other way is to hide the
gridlines. Write the sentence and file a bug report.

You may file the bugreport to me (I'll see, If I get direct commit
access for help files - well actually I even have that I think).

OK, well I'll bookmark this for attention when I get time. Maybe
someone else would like to step up and take this on?

Imho documentation team should have the lead for product and online
help. Developers should only be involved for the commit to the source
repository.

Well, I agree that this would be logical. However, we're a bit
short-handed right now to organize this properly. Again, are we
lacking a software tool that would interface the devs better with the
documentation and design teams? I think that theoretically Alfresco
could provide the answer, although that would require some design and
development work to implement. Is there some other interim or
permanent solution?

Hi,

Are we lacking some kind of software tool to help bring teams together?

A tool might improve collaboration, if people are aware what
could/should be done best by whom.
A tool does only pretend to improve collaboration if people are not yet
aware that there is a need for collaboration.

Is it worth putting this subject on the agenda of an SC meeting and
talking about it voice there?

Not - yet. As told somewhere else in the thread(s) - I'm going to think
about improvements later and then start discussion (needs to be
discussed with more developers). This is not necessarily a topic for the
SC, I much prefer the community to be self-organizing.

regards,

André

Hi :slight_smile:
The Devs List/Team has far more people than the Documentation Team/List. So
although there are lots of good ideas that would be great to do there is very
limited potential to actually do those things. Obviously actually doing
documentation work needs to be the priority.

It would be great if every mailing list had a couple of people on every other
mailing list. I'm on Steering-discuss, Steering and Users. When issues appear
in one of those lists that really needs to go to another one of those lists or
needs to hear about outcomes of discussions on another list then i can try to
forward relevant emails. However just 4 lists takes up so much of my time that
i can't get actively involved in actually doing any of the real work in any of
the teams. If other people in the documentation team followed the same lists as
me then no documentation work would ever get done.

There has to be a better way of getting an overview of the activities of several
groups than is possible using mailing lists.
Regards from
Tom :slight_smile:

Hi again,
I have seen something called "Forums" in other projects.

It's a bit like the bug-reporting place. Rather than getting bombarded by vast
amount of irrelevant emails the user actively goes to the sites. Good ones
allow people to subscribe to specific threads about particular issues. The
threads are sorted into sub-categories within main categories that could be the
main groups. There can even be a column that shows how recently the last post
appeared in a sub-category so that people can keep an eye on what are active
issues. Something like

Documentation Team
    Collaboration with other lists
    New members
    Screen-shots
    Writer
    Calc
    Draw
    Base
    OOo & ODFauthors
Devs Team
    New members
    Javascript
    DocX compatibility
    Base
Users
    DocX compatibility
    Side-by-side with OOo (or another LO version)
    Stability in 3.4.x branch
    Installing
    Training & Documentation
Steering-Discuss
    New members
    Training
    Governance, Rules and T&Cs
    Licences
    Branches & forks
    OOo

Obviously there would be a LOT more per group and some of those sub-categories
might need to contain sub-sub-categories just like any filing system.
  
The main point is that someone might want to hear all about Writer and
compatibility with other projects but might be completely dis-interested in
hearing anything about Base = or the other way around. People might pop-in to
ask 1 question about some minor issue and not want to hear detailed blow-by-blow
accounts of how 500 other users are dealing with other minor issues.

If we used forums rather than mailing lists i might be able to get involved in
some real work here. At the moment i don't.
Regards from
Tom :slight_smile:

Hi :slight_smile:
+1
David's changes make it clearer. It didn't take much because the original was
quite good.

The problem with asking for help is that while the question might seem obvious
to the person asking there might be a large number of variables that they might
be unaware of. Usually someone in the answering team will ask questions to find
out precisely what is being asked. Hopefully they might be able to take a guess
at an answer in the same email.

At work one of my colleagues said his "computer was totally f@*$%^d". He asked
me for help but wouldn't let me see or handle the machine and wouldn't answer
any of my questions about it. This went on for about 2 days. When i finally
managed to get him to answer about 3 simple questions i was able to fix it in 3
mouse-clicks taking about 1minute. The next time he told me his machine was
completely dead he answered my 1st question a lot faster so instead of being
down for 2 days he was back almost seemlessly. The 3rd time he just wanted me
to watch while he fixed it himself. After that people stopped bothering to set
his Windows to open with a single-click rather than a double-click.

Much the same seemed to happen here. Quite a few people asked Andre
specifically what the text was that he wanted proof-reading and where that text
appears but all he did was keep repeating the links to the wiki-page that all
looked perfect. As soon as we found out what text needed editing it was easy to
help.

The failure to help was not to do with the system nor the software used. Next
time we have to deal with questions from devs we now know that it might help to
find the bug-report / feature-request thread at freedesktop or where-ever.

Regards from
Tom :slight_smile: