Re: Rebooting the Documentation Effort

[toki]

On 22/01/2016 02:30, Keith N. McKenna wrote:

>> How justifiable is it to disparage what is currently going on when
doing nothing to alleviate the problem.

I realize that there are some who think that pointing out that there is
no new product, is disparaging of the organization that did not make a
new product.

I also realize that there are some who think that it is disparaging to
have a proposal that goes against the corporate culture.

I also realize that there are some who consider it disparaging for a
proposal to be made, that includes disclaimers and reasons why the
proposal should be rejected.

>  even writing or editing existing high level documents

All of the documentation I've written in the last five years, has not
been distributed by the organization who created/developed/provide tech
support for the software. As such, individuals within those
organizations are not necessarily aware of that documentation.

jonathon


-
To unsubscribe, e-mail: doc-unsubscr...@openoffice.apache.org
For additional commands, e-mail: doc-h...@openoffice.apache.org

Re: Rebooting the Documentation Effort

[Andrea Pescetti]

Keith N. McKenna wrote:

Personally I had enough political and turf battles when I
worked in the corporate world; I certainly do not need them now


Sure. You are coordinating volunteers here without the need of any 
formal structure. No need for any structure. Volunteers are here, we had 
more documentation progress in the last quarter than in the entire prior 
year and this groups is getting something done, with a productive 
attitude and without any useless discussions. Guys, you should be proud 
of what you are doing and just keep going. The effort is huge but things 
are happening.


Keith, would you like to change the Wiki home page to point directly at 
the new documentation? This may be a way to involve more people.


Regards,
  Andrea.

-
To unsubscribe, e-mail: doc-unsubscr...@openoffice.apache.org
For additional commands, e-mail: doc-h...@openoffice.apache.org

Re: Rebooting the Documentation Effort

[Keith N. McKenna]

Dennis E. Hamilton wrote:
> Response below,
> 
>> -Original Message- From: Keith N. McKenna
>> [mailto:keith.mcke...@comcast.net] Sent: Wednesday, January 20,
>> 2016 18:39 To: doc@openoffice.apache.org Subject: Re: Rebooting the
>> Documentation Effort
> [ ... ]
>> 
>> It is all well and good to talk about having the more experienced 
>> project people take a role in assigning tasks et. al. However we
>> are in the position we are in because we do not have the
>> experienced people. We were told on the dev list to go ahead and
>> create a doc mailing list and make the decisions on how the
>> documentation should be structured and all that. Now we are being
>> told that we should be making those decisions on the dev list.
>> Personally I had enough political and turf battles when I worked in
>> the corporate world; I certainly do not need them now that I am
>> retired and doing this on a volunteer basis.
>> 
>> I have done what I am able to do and I will step back and others
>> more qualified battle it out. I hope that you can find a solution
>> but I am not sanguine on that score. As is often the case on large
>> and small projects alike, Documentation is the bastard child that
>> nobody likes admit exists.
>> 
>> Regards Keith
> [orcmid]
> 
> Keith,
> 
> Please.  I am saying that things like voting aren't part of how ASF
> projects work on a routine basis, nor is assigning tasks something
> that is done.  We can discuss separately how one operates instead
> while still having a coordinated effort.
> 
> The idea is to operate by consensus.  And people are permitted to
> act.  On the wiki, as for other tools, nothing is irreversible, and
> mistakes are easily corrected.  If disagreements arise, let's worry
> about that whenever something like that happens.
> 
> I assume a lot of silent consensus is the case with those who operate
> here.
> 
> But for major things, that do require deliberation, the only
> mechanism is at dev@ where the whole community is involved.  I have
> no idea what one of those might be for work on the documentation.  So
> far, I know of no need.
> 
> Voluntary activity is just that and it should continue where it fits
> best.  None of this suggests the contributors to the wiki need to
> change anything.
> 
> I only want to point out to Dave that we don't operate by creating
> leadership structures, voting on who those are, etc.  I was agreeing,
> as I expect you do also, that having some seasoned writers and people
> who know the product well would be very helpful in advancing the
> documentation.
> 
> No one voted for you, you rolled up your sleeves and you are making
> this amazing effort.  People respect what you are doing and
> participate.  You are supporting the wiki roster and authorization of
> editors as a volunteer task.  I don't recall there being any high
> ceremony involved.
> 
> That is how it is meant to work.
> 
> Take a breath, please.
> 
> - Dennis
> 
Dennis;

I have been taking multiple breaths over the last 3 years as we have
muddled through multiple variations of the same rat-hole discussions
about having more structure or less structure, this license or that
license, wiki based or not etc etc. ad infinitum. Meanwhile the
documentation grows more and more out of date, and volunteers grow
frustrated and go elsewhere.

Frankly the more I see the more convinced I become that we will never
have solid, sustainable  documentation for the product. The skills
necessary to do that either are not there in the project community or if
they are people have chosen for there own very valid reasons not
contribute to the documentation effort. Without a few core people that
have an intimate working knowledge of the process of technical writing
to guide others getting to the goal of high quality, sustainable
documentation is going to be very difficult.

Regards
Keith



signature.asc
Description: OpenPGP digital signature

Re: Rebooting the Documentation Effort

[Keith N. McKenna]

Andrea Pescetti wrote:
> Keith N. McKenna wrote:
>> Personally I had enough political and turf battles when I
>> worked in the corporate world; I certainly do not need them now
> 
> Sure. You are coordinating volunteers here without the need of any
> formal structure. No need for any structure. Volunteers are here, we had
> more documentation progress in the last quarter than in the entire prior
> year and this groups is getting something done, with a productive
> attitude and without any useless discussions. Guys, you should be proud
> of what you are doing and just keep going. The effort is huge but things
> are happening.

Thank you for the pep talk Andrea. It is just very disheartening that at
the time when it looks like there is sustainable progress happening that
the same old potentially divisive conversations start-up again.
> 
> Keith, would you like to change the Wiki home page to point directly at
> the new documentation? This may be a way to involve more people.

Andrea;
Let me think on that one a bit. I can see the advantage of possibly
attracting more people, but there is also the down side of the new stuff
being still very rough or even non-existent that it frustrates people
trying to use it to get answers to there immediate needs.

Maybe with enough cautionary wording the advantages could out-weigh the
disadvantages.

Regards
Keith
> 
> Regards,
>   Andrea.




signature.asc
Description: OpenPGP digital signature

Re: Rebooting the Documentation Effort

[toki]

-BEGIN PGP SIGNED MESSAGE-
Hash: SHA1

On 21/01/2016 19:47, Keith N. McKenna wrote:

> this license or that license,

ASF pretty much dictates that the Apache License be used.

>wiki based or not etc etc. ad infinitum.

That is a clash of psycho-epistemological Weltanschauung. A clash that
will probably remain until the diaper set are the PHBs.

If there are enough editors, etc, then all formats can be supported.  If
they aren't, then does the documentation effort support marketing AOO to
the corporate world, or marketing AOO to students, or marketing AOO to
individuals?

Thus far, the focus of the documentation project has been on supporting
the marketing of AOO to students, not individuals, and not the corporate
world.

> Meanwhile the documentation grows more and more out of date, and
volunteers grow frustrated and go elsewhere

How out of date the documentation is, depends upon what specific piece
one is looking at.

I focus on printed manuals/PDFs.

> the fact remains that if no one steps forward with the necessary skill
s to fulfill the role you propose it is not going to happen.

There is a fundamental disconnect between what I outlined, and The
Apache Way.

a) The emails are person to person, not person to group;
b) "You do" violates a core principle --- all are equals;
c) It requires a person who not only makes decisions, but enforces them,
_regardless_ of group input.

jonathon


-BEGIN PGP SIGNATURE-
Version: GnuPG v2.0.22 (GNU/Linux)

iQIcBAEBAgAGBQJWoU9fAAoJEKG7hs8nSMR7gZkP/Ay4KsfWJgq6ROVODlXpqrqj
3GydH6y4bTkTv7SaSm1ze6AKm1mlB/gFxbpz2ldEI2GzRYCr4/PVJrXfsjrOZpMq
VCLhKIQ5rpL5gWxmKfACuXwcGromoF4/6Jp1YPiiY8o/l3/t81BOqkMAtcrWVAeX
1LP5nwvDZz58gaTK0FcV/O6o5XWMM8vtW0MSjOn8eOHNr8xBcWKETHwxCNNGieBr
6ngV/Wv+uI+6iX/FbU32ErENpsPrtCKm2380LCK8rYM9Z14Kdm9AprI7ESY8WhTG
WnBAwjgxCMVC0uNo2gUFb7WbuGFIQHZeq15MfLxL8LTA0MmUMOLoxy9fpIK0+YNY
FryIcw9W7dE10xfzgpS3nXbDAliij+Q8WV+pkMMIzMgFqsHjqseXOkBoASLe7t2S
79X1iw2ouXWEpDW7X2Rl1yIyXo+TxxqKdYbi59NfpDde+HsWR2Y1t1TwV0SPj3K+
TQ8SAP6BxhXnAOIcSznXJOgqb7JXcpFis42Sun5Zf29QqKjhtR857pvG5S2YZLBm
PG5QHOi9qnAkfKL7ZKUdwpBvKpeGrIEoG8FR4If618gL7Y6HxW5y4nDakp1b/pOz
him8HrOMGKMCa7qpmasLbT3uGPamvA3458WnjSfGz66/4hoTOizNZtV+f5bgnX/c
YcJgxfybOojs9vQjtaUX
=8kFC
-END PGP SIGNATURE-

-
To unsubscribe, e-mail: doc-unsubscr...@openoffice.apache.org
For additional commands, e-mail: doc-h...@openoffice.apache.org

Re: Rebooting the Documentation Effort

[Keith N. McKenna]

toki wrote:
> On 21/01/2016 23:26, Keith N. McKenna wrote:
> 
>> Actually that is incorrect.
> 
> You're not looking at psycho-demographic groups, based upon their
> preferred formats for receiving new data.
> 
> What the documentation states it is focused upon means squat.
> 
>> but if you are not willing or able to step forward and volunteer to ta
> ke a crack at getting it working than all one is
> 
> The quandary is that everything outlined being contrary to The Apache Wa
> y.
> 
> How justifiable is it to totally smash The Apache Way to smithereens, to
> accomplish the desired goal --- documentation that is current, and
> supports marketing AOO to students, individuals, and the corporate world
> ?
> 
How justifiable is it to disparage what is currently going on when doing
nothing to alleviate the problem. You present yourself as someone who
has the editing skills to help alleviate the problem, but I see no
evidence that you have done anything to improve the process or the
documentation itself except occasionally pontificate on the list and
taking no concrete action to help in anyway.

When you want to constructively participate by mentoring volunteers or
editing documentation or even writing or editing existing high level
documents that can be used to improve the product we are trying to
develop then we can continue this fascinating conversation.

Regards
Keith
> jonathon
> 




signature.asc
Description: OpenPGP digital signature

Re: Rebooting the Documentation Effort

[Keith N. McKenna]

toki wrote:
> On 20/01/2016 23:02, Dennis E. Hamilton wrote:
> 
>> I think that having a structure for contributors finding work and also
>  finding any guidance they need is a great idea.
> 
> One individual whose sole function is to say: "Do this", and then
> follows up weekly, to see how "this" is progressing, and sending help
> that way, when needed.
> 
> "Do this" can be writing, copy-editing, proofreading, translating, line
> editing, or maybe even plot editing the document.
> 
> "The document" can be an entire manual, a chapter, a sub-chapter, how-to
> for something that ends up on the wiki, dead tree printed, and PDF.  In
> future, that might expand to include the Presentation format, video, and
> audio version.
> 
> When somebody sends an email saying "I'd like to help with the
> documentation project". The first response is: "Which of the follow
> skills do you have? Line editing, copy editing, blah, blah, blah." The
> second response is: "Here is x document, go do blah", where blah is a
> skill that the individual claimed.
> 
> If the new-volunteer claims no skills, then they are given a list of
> books to study, so that they can learn the appropriate skills. If need
> be, they are also given tests, to demonstrate how well they know the
> appropriate skill.
> 
> No sending people to a wiki page to read, and decide what they would
> like to do for the documentation project.
> No waiting for people to ask for help in doing something.
> 
>> We need a way for that to be self-organizing without any kind of hiera
> rchy or leadership roles.
> 
> You can either have a team that produces a new user manual every
> quarter, or a team that meanders along, putting out one updated user
> manual every three years.
> 
> The difference is whether each team member is specifically asked to
> write/do something, or if things are left to each individual to step
> forward.
> 
>> That needs to be used in an organic way, with everything operating by
> consensus to the max.
> 
> For some things, you simply have to have one person say "This way, and
> only this way". To do otherwise is to waste way too much time in
> discussing, and maybe voting on otherwise trivial issues. 10th, 11th,
> 12th, 13th, 14th, 15th, 16th, 17th, or 18th edition of Chicago being a
> prime example. I bring Chicago up, precisely because experienced editors
> have their own favourite version, and, unless it made clear up front,
> exactly which version to use, will either use their favourite version,
> or, more commonly, try to persuade everybody to use that version,
> instead of getting on with the task at hand.
> 
>> It may be that there is a bit more-than-usual process structure here f
> or producing documentation on the Wiki and elsewhere.
> 
> The ideal is that the same source document can be used, with minimal
> massaging, in the wiki, the F1 Help file, the dead tree manual, the ePub
> manual, the PDF manual, the video script, the audio script, and where
> ever else documentation needs to be found.
> 
> Right now, that isn't even hypothetically possible. However, if the
> ground work is laid today, in five to seven years, that could be the
> reality.
> 
>> The idea is to build communities that are consensus-focused in their
> operation.
> 
> Writing documentation is not writing FanFic.
> Parleying it into a paying gig is pretty much a non-starter.
> 
>> Formal deliberations must be on the dev@ list, not here on doc@, and
> the binding votes are from the Project Management Committee members,
> 
> How many Project Management Committee members know the difference
> between the 1oth, 11th, 12th, 13th, 14th, 15th, 16th, 17th, and 18th
> edition of Chicago, well enough to be understand why one might not want
> to go with the 19th edition?
> 
> Whilst fundamental to what the final work product looks like, it is
> trivial, in that for publishing houses, which edition to use is the
> first decision made by the senior editor, after they are hired. (This
> applies as much to brand new startups, as it does to the Five Sisters.)
> 
> jonathon
>
Jonathon;

Though I do not necessarily disagree with much of what you said, the
fact remains that if no one steps forward with the necessary skills to
fulfill the role you propose it is not going to happen. As you appear to
have the requisite skills, in the spirit of
the "Apache Way" are you stepping forward to take on that responsibility?

Regards
Keith






signature.asc
Description: OpenPGP digital signature

Re: Rebooting the Documentation Effort

[Keith N. McKenna]

Dennis E. Hamilton wrote:
> Dave, I think that having a structure for contributors finding work and also 
> finding any guidance they need is a great idea.  Finding some experienced 
> hands to contribute that sort of guidance and help organize effort to some 
> degree would be valuable.
> 
> We need a way for that to be self-organizing without any kind of hierarchy or 
> leadership roles.  For ASF projects, we seek a way for leadership to emerge 
> where needed but not that there are positions or titles.  
> 
> It looks like there are structures on the Wiki itself that can be used to 
> help folks channel contributions and have it be coordinated among them.  That 
> needs to be used in an organic way, with everything operating by consensus to 
> the max.
> 
> It may be that there is a bit more-than-usual process structure here for 
> producing documentation on the Wiki and elsewhere.  I think some of this is 
> historical, preceding the migration to Apache OpenOffice.  Some parts are 
> important aids for coordination and also providing an account for effort, 
> changes, etc.
> 
>  - Dennis
> 
> A little background:
> 
> ASF Projects have flat organization and depend on volunteer contribution.  
> The idea is to build communities that are consensus-focused in their 
> operation.  Voting is considered a last resort although it is required for 
> certain activities (such as approving a release).  Formal deliberations must 
> be on the dev@ list, not here on doc@, and the binding votes are from the 
> Project Management Committee members, although all votes are considered. 
> There's not supposed to be any other formal process than that.  There are 
> legal and ASF Charter reasons that there is even that much structure, such as 
> every project having a Chair that is an Officer of the Foundation.
> 
> 
>> -Original Message-
>> From: Dave [mailto:davepo...@gmail.com]
>> Sent: Wednesday, January 20, 2016 14:21
>> To: doc@openoffice.apache.org
>> Subject: Re: Rebooting the Documentation Effort
>>
>> Hi all,
>>
>> I think we do need a group of half a dozen people with a lot of
>> experience
>> of the project to distribute the work amongst the others. This group
>> would
>> need to decide collectively what needs to be done and in what order of
>> priority. They would have to be democratically elected by the rest of
>> us...
>>
>> Regards, Dave
>>
>> 2016-01-20 21:57 GMT+01:00 Keith N. McKenna <keith.mcke...@comcast.net>:
>>
>>> Dennis E. Hamilton wrote:
>>>> [bcc: dev@]
>>>>
>>>> Hi Keith,
>>>>
>>>> I have belatedly noticed your efforts to reboot the documentation
>>>> effort, first in April and again in December, 2015.
>>>>
>>>> I commend you on this.
>>>
>>> Thank You Dennis, I appreciate it.
>>>>
>>>> While people raise their hands, we don't seem to achieve traction.
>>>>
>>>> I would like to know from those who did not persevere,
>>>>
>>>> What got in the way?
>>>>
>>>> Is it all a matter of life intervening?
>>>>
>>>> Are there technical and communication matters that can be addressed
>>>> to remove any barriers that were encountered?
>>>>
>>>> Is there missing information?
>>>>
>>>> - Dennis
>>>>
>>> I cannot speak for others, but  I will add my own observations for
>>> whatever use they may be.
>>>
>>> I think a lot of people raise their hand to volunteer with the
>>> expectation that there will be a lot of mentoring, task assignments
>> and
>>> that sort of thing. We do not have experienced people to do mentoring
>> to
>>> that level. I am not a tech writer. I am a Manufacturing Engineer that
>>> has written some technical documentation as a part of my job. As far
>> as
>>> task assignments I believe that each contributor knows best there
>>> strengths and are better able to know what they might be best at. If
>>> someone wants to take on the task of handing out assignments for new
>>> volunteers I think that could be a help.
>>>
>>> Given the recent level of activity, I am cautiously optimistic that we
>>> may see some more forward momentum.
>>>
>>> Regards
>>> Keith
>>>
>>>
>>>
>>>
Gentleman;

It is all well and good to talk about having the more experienced
project people take a role in assigning tasks et. al. However we are in
the posit

RE: Rebooting the Documentation Effort

[Dennis E. Hamilton]

Response below,

> -Original Message-
> From: Keith N. McKenna [mailto:keith.mcke...@comcast.net]
> Sent: Wednesday, January 20, 2016 18:39
> To: doc@openoffice.apache.org
> Subject: Re: Rebooting the Documentation Effort
[ ... ]
> 
> It is all well and good to talk about having the more experienced
> project people take a role in assigning tasks et. al. However we are in
> the position we are in because we do not have the experienced people. We
> were told on the dev list to go ahead and create a doc mailing list and
> make the decisions on how the documentation should be structured and all
> that. Now we are being told that we should be making those decisions on
> the dev list. Personally I had enough political and turf battles when I
> worked in the corporate world; I certainly do not need them now that I
> am retired and doing this on a volunteer basis.
> 
> I have done what I am able to do and I will step back and others more
> qualified battle it out. I hope that you can find a solution but I am
> not sanguine on that score. As is often the case on large and small
> projects alike, Documentation is the bastard child that nobody likes
> admit exists.
> 
> Regards
> Keith
[orcmid] 

Keith,

Please.  I am saying that things like voting aren't part of how ASF projects 
work on a routine basis, nor is assigning tasks something that is done.  We can 
discuss separately how one operates instead while still having a coordinated 
effort.

The idea is to operate by consensus.  And people are permitted to act.  On the 
wiki, as for other tools, nothing is irreversible, and mistakes are easily 
corrected.  If disagreements arise, let's worry about that whenever something 
like that happens.

I assume a lot of silent consensus is the case with those who operate here.

But for major things, that do require deliberation, the only mechanism is at 
dev@ where the whole community is involved.  I have no idea what one of those 
might be for work on the documentation.  So far, I know of no need.

Voluntary activity is just that and it should continue where it fits best.  
None of this suggests the contributors to the wiki need to change anything.

I only want to point out to Dave that we don't operate by creating leadership 
structures, voting on who those are, etc.  I was agreeing, as I expect you do 
also, that having some seasoned writers and people who know the product well 
would be very helpful in advancing the documentation.

No one voted for you, you rolled up your sleeves and you are making this 
amazing effort.  People respect what you are doing and participate.  You are 
supporting the wiki roster and authorization of editors as a volunteer task.  I 
don't recall there being any high ceremony involved.

That is how it is meant to work.

Take a breath, please.

 - Dennis







-
To unsubscribe, e-mail: doc-unsubscr...@openoffice.apache.org
For additional commands, e-mail: doc-h...@openoffice.apache.org

Re: Rebooting the Documentation Effort

[toki]

-BEGIN PGP SIGNED MESSAGE-
Hash: SHA1

On 20/01/2016 23:02, Dennis E. Hamilton wrote:

> I think that having a structure for contributors finding work and also
 finding any guidance they need is a great idea.

One individual whose sole function is to say: "Do this", and then
follows up weekly, to see how "this" is progressing, and sending help
that way, when needed.

"Do this" can be writing, copy-editing, proofreading, translating, line
editing, or maybe even plot editing the document.

"The document" can be an entire manual, a chapter, a sub-chapter, how-to
for something that ends up on the wiki, dead tree printed, and PDF.  In
future, that might expand to include the Presentation format, video, and
audio version.

When somebody sends an email saying "I'd like to help with the
documentation project". The first response is: "Which of the follow
skills do you have? Line editing, copy editing, blah, blah, blah." The
second response is: "Here is x document, go do blah", where blah is a
skill that the individual claimed.

If the new-volunteer claims no skills, then they are given a list of
books to study, so that they can learn the appropriate skills. If need
be, they are also given tests, to demonstrate how well they know the
appropriate skill.

No sending people to a wiki page to read, and decide what they would
like to do for the documentation project.
No waiting for people to ask for help in doing something.

> We need a way for that to be self-organizing without any kind of hiera
rchy or leadership roles.

You can either have a team that produces a new user manual every
quarter, or a team that meanders along, putting out one updated user
manual every three years.

The difference is whether each team member is specifically asked to
write/do something, or if things are left to each individual to step
forward.

> That needs to be used in an organic way, with everything operating by
consensus to the max.

For some things, you simply have to have one person say "This way, and
only this way". To do otherwise is to waste way too much time in
discussing, and maybe voting on otherwise trivial issues. 10th, 11th,
12th, 13th, 14th, 15th, 16th, 17th, or 18th edition of Chicago being a
prime example. I bring Chicago up, precisely because experienced editors
have their own favourite version, and, unless it made clear up front,
exactly which version to use, will either use their favourite version,
or, more commonly, try to persuade everybody to use that version,
instead of getting on with the task at hand.

> It may be that there is a bit more-than-usual process structure here f
or producing documentation on the Wiki and elsewhere.

The ideal is that the same source document can be used, with minimal
massaging, in the wiki, the F1 Help file, the dead tree manual, the ePub
manual, the PDF manual, the video script, the audio script, and where
ever else documentation needs to be found.

Right now, that isn't even hypothetically possible. However, if the
ground work is laid today, in five to seven years, that could be the
reality.

> The idea is to build communities that are consensus-focused in their
operation.

Writing documentation is not writing FanFic.
Parleying it into a paying gig is pretty much a non-starter.

>Formal deliberations must be on the dev@ list, not here on doc@, and
the binding votes are from the Project Management Committee members,

How many Project Management Committee members know the difference
between the 1oth, 11th, 12th, 13th, 14th, 15th, 16th, 17th, and 18th
edition of Chicago, well enough to be understand why one might not want
to go with the 19th edition?

Whilst fundamental to what the final work product looks like, it is
trivial, in that for publishing houses, which edition to use is the
first decision made by the senior editor, after they are hired. (This
applies as much to brand new startups, as it does to the Five Sisters.)

jonathon
-BEGIN PGP SIGNATURE-
Version: GnuPG v2.0.22 (GNU/Linux)

iQIcBAEBAgAGBQJWoHZWAAoJEKG7hs8nSMR7wVEP/0QT1sJse8Z/aTisqtOr06OA
VDWhiW61ch/FOJo8PWXEg57W3Coi/mO6lGkBkUtulBjwfAYpmaMs9jKYuK+WmCjN
94mh5yZAfAHnITwhK482K5KASCWZ0AsngSekcdIMtkp6ij/HXTCMYOtaky5+aN0r
dDbHHpB7xskjD5mnMHC0mAghWYbAs7SXx0fS/t1xQLZ5H+cKoIpLcnr3orIt729N
d6kYomMwUSRqYtCOMkoFsCXGHT68MV9GtV5RIYf+iEewPHJjeHoASRd+kCwnD8kI
WYD+ynyWGmC6avDg685OfXhtEW/E7d4f+Kbr4pEZdDdKvGvB27W/jY793lFhJzxK
M/mZD604vlAg0OQo2lixY6EXhhqQXF+o5ZTcVck1Pb4pnhGqx/pi2LGMVzWp0shr
buMKl11xcc79dLcwkkOcLz3IooLqoUZou7vwR1DWcWj6dyb7RhxOyaP/vwnNZMEl
x+7aKc4a6bWZ9NZ1hjTkaWGPtQiYOSlqf6mvbmZNbZcKE3tGo1Md6LpTPpI9MXaZ
W3LYFIHu0+Pz9rt6AZMmsR/kROUM2PcB33M7q7LiDw3I5YdwYS2ceps0/uouKF5T
QT934jcSTYyj+glt8AP71d9QCFBq8z4Ooc/erCu6ap8XbvLDI9yY+V8FREgE3g22
m/1DlsM3lbOfHdoHDN4y
=2pqF
-END PGP SIGNATURE-

-
To unsubscribe, e-mail: doc-unsubscr...@openoffice.apache.org
For additional commands, e-mail: doc-h...@openoffice.apache.org

Re: Rebooting the Documentation Effort

[Keith N. McKenna]

Dennis E. Hamilton wrote:
> [bcc: dev@]
> 
> Hi Keith,
> 
> I have belatedly noticed your efforts to reboot the documentation
> effort, first in April and again in December, 2015.
> 
> I commend you on this.

Thank You Dennis, I appreciate it.
> 
> While people raise their hands, we don't seem to achieve traction.
> 
> I would like to know from those who did not persevere,
> 
> What got in the way?
> 
> Is it all a matter of life intervening?
> 
> Are there technical and communication matters that can be addressed
> to remove any barriers that were encountered?
> 
> Is there missing information?
> 
> - Dennis
> 
I cannot speak for others, but  I will add my own observations for
whatever use they may be.

I think a lot of people raise their hand to volunteer with the
expectation that there will be a lot of mentoring, task assignments and
that sort of thing. We do not have experienced people to do mentoring to
that level. I am not a tech writer. I am a Manufacturing Engineer that
has written some technical documentation as a part of my job. As far as
task assignments I believe that each contributor knows best there
strengths and are better able to know what they might be best at. If
someone wants to take on the task of handing out assignments for new
volunteers I think that could be a help.

Given the recent level of activity, I am cautiously optimistic that we
may see some more forward momentum.

Regards
Keith





signature.asc
Description: OpenPGP digital signature

RE: Rebooting the Documentation Effort

[Dennis E. Hamilton]

Dave, I think that having a structure for contributors finding work and also 
finding any guidance they need is a great idea.  Finding some experienced hands 
to contribute that sort of guidance and help organize effort to some degree 
would be valuable.

We need a way for that to be self-organizing without any kind of hierarchy or 
leadership roles.  For ASF projects, we seek a way for leadership to emerge 
where needed but not that there are positions or titles.  

It looks like there are structures on the Wiki itself that can be used to help 
folks channel contributions and have it be coordinated among them.  That needs 
to be used in an organic way, with everything operating by consensus to the max.

It may be that there is a bit more-than-usual process structure here for 
producing documentation on the Wiki and elsewhere.  I think some of this is 
historical, preceding the migration to Apache OpenOffice.  Some parts are 
important aids for coordination and also providing an account for effort, 
changes, etc.

 - Dennis

A little background:

ASF Projects have flat organization and depend on volunteer contribution.  The 
idea is to build communities that are consensus-focused in their operation.  
Voting is considered a last resort although it is required for certain 
activities (such as approving a release).  Formal deliberations must be on the 
dev@ list, not here on doc@, and the binding votes are from the Project 
Management Committee members, although all votes are considered. There's not 
supposed to be any other formal process than that.  There are legal and ASF 
Charter reasons that there is even that much structure, such as every project 
having a Chair that is an Officer of the Foundation.


> -Original Message-
> From: Dave [mailto:davepo...@gmail.com]
> Sent: Wednesday, January 20, 2016 14:21
> To: doc@openoffice.apache.org
> Subject: Re: Rebooting the Documentation Effort
> 
> Hi all,
> 
> I think we do need a group of half a dozen people with a lot of
> experience
> of the project to distribute the work amongst the others. This group
> would
> need to decide collectively what needs to be done and in what order of
> priority. They would have to be democratically elected by the rest of
> us...
> 
> Regards, Dave
> 
> 2016-01-20 21:57 GMT+01:00 Keith N. McKenna <keith.mcke...@comcast.net>:
> 
> > Dennis E. Hamilton wrote:
> > > [bcc: dev@]
> > >
> > > Hi Keith,
> > >
> > > I have belatedly noticed your efforts to reboot the documentation
> > > effort, first in April and again in December, 2015.
> > >
> > > I commend you on this.
> >
> > Thank You Dennis, I appreciate it.
> > >
> > > While people raise their hands, we don't seem to achieve traction.
> > >
> > > I would like to know from those who did not persevere,
> > >
> > > What got in the way?
> > >
> > > Is it all a matter of life intervening?
> > >
> > > Are there technical and communication matters that can be addressed
> > > to remove any barriers that were encountered?
> > >
> > > Is there missing information?
> > >
> > > - Dennis
> > >
> > I cannot speak for others, but  I will add my own observations for
> > whatever use they may be.
> >
> > I think a lot of people raise their hand to volunteer with the
> > expectation that there will be a lot of mentoring, task assignments
> and
> > that sort of thing. We do not have experienced people to do mentoring
> to
> > that level. I am not a tech writer. I am a Manufacturing Engineer that
> > has written some technical documentation as a part of my job. As far
> as
> > task assignments I believe that each contributor knows best there
> > strengths and are better able to know what they might be best at. If
> > someone wants to take on the task of handing out assignments for new
> > volunteers I think that could be a help.
> >
> > Given the recent level of activity, I am cautiously optimistic that we
> > may see some more forward momentum.
> >
> > Regards
> > Keith
> >
> >
> >
> >


-
To unsubscribe, e-mail: doc-unsubscr...@openoffice.apache.org
For additional commands, e-mail: doc-h...@openoffice.apache.org

Re: Rebooting the Documentation Effort

[toki]

-BEGIN PGP SIGNED MESSAGE-
Hash: SHA1

On 18/01/2016 22:22, David Lloyd-Jones wrote:

> Fundamentally, why should software need documenting?

AOo obviously includes all of the functionality that is requested in
3959.  Making use of that functionality is highly non-obvious, and
arguably anti-intuitive.

As such, what is clearly lacking, is the documentation that enables mere
mortals to easily do that which is requested in 3959, using AOo 4.12.

And that underscores how important it is that software be fully
documented, for both developers, and users.

> don't document doors or refrigerators, stairs or elevators.

FWIW, documentation for all of those items is created, and distributed.

> If a piece of software can't document itself on the first screen up, t
hen the hell with it.

That works for only the most trivial, simple software.
"Hello World", being a prime candidate.

> You can stop pretending you're typing on a piece of paper now.

A lot of those PDFs get printed on A4 or A5 paper.

jonathon

-BEGIN PGP SIGNATURE-
Version: GnuPG v2.0.22 (GNU/Linux)

iQIcBAEBAgAGBQJWnY/dAAoJEKG7hs8nSMR7zBgP/jtyCAUnC56bWdnWyc85W3TS
4VmVVbLX4W8VwbNJiT3IQLcAU0RZeuZtrdYojNFuf87asUj3WPj7wgkrU2qgm2XT
6l7TUyD3cEk6u0thaQ+OKfEV38kYNXhk//d9Bb7fCiCZU4MDabcdyQv8MvU7blYC
sKYInAidFN3S5jEX3rEfDQd/Em7u1kK5xM+y7qRAToomhIeemlojcblhaff+G3Na
D3HyT5OrGHL39JQYRkmoBC/F+VQ5Skxx1tngVzcOjcdKbRrs/WMOKwUNDuLXpz9h
+xj65LUw/nGaQWOZJD+yoi7UzmVTckI13fsQ/Jf2e0ESUjfqxhnFg2lchJPG16hD
j8+hQWHlY4CaaNa8ZqtaYdecpQfGIsCnZlkUiwrB2vf1GOqh1F30eaeifw2B/ssT
VJ11DyXSU6D0DP34K+p2iHO09cyfGQVqLF7YgA9a8BnRc4VNNldjviayFvqE0u5+
W6VmbWQwCd5+Cm5t7JqMvxeus7wxNmvF4HUQgROQnSrJyMqWawWVhqr7JuH2Lg3/
fEvJLSc+7ZuBZ1DAUgBOFNggu8G9ko4D1JPsetCGXYc2F1rX/Ah2pnbjdidJorHZ
+FhoS9kCAJTGCYCYYspazIkca4iEM9/u0e0QM28eBQ0hPytTCYXKzmpQ6EZubKvW
2q/5WEEarWQENrRvgCpp
=xuxp
-END PGP SIGNATURE-

-
To unsubscribe, e-mail: doc-unsubscr...@openoffice.apache.org
For additional commands, e-mail: doc-h...@openoffice.apache.org

Re: Rebooting the Documentation Effort

[David Lloyd-Jones]

Dennis & Keith,

I think one of the problems in the world now is that there is too much
documentation.  Fundamentally, why should software need documenting?  We
don't document doors or refrigerators, stairs or elevators.

I blame it all on Jimmy Carter and the Nobel folks: he got the Israelis and
the Palestinians together and he bored them into submission, and then the
Swedes gave him a Nobel for it.  Ever since that time people have been
nattering on and on and on, hoping that they'll get a Nobel, too.

If a piece of software can't document itself on the first screen up, then
the hell with it.

-dlj.

P.S. A note for the folks at Adobe -- and for that matter everybody else in
document world: the aspect ratio of a computer screen is 4x5 sideways.  It
is not eight-and-a-half by eleven vertical.

You can stop pretending you're typing on a piece of paper now.

-d.




On 18 January 2016 at 16:18, Dennis E. Hamilton  wrote:

> [bcc: dev@]
>
> Hi Keith,
>
> I have belatedly noticed your efforts to reboot the documentation effort,
> first in April and again in December, 2015.
>
> I commend you on this.
>
> While people raise their hands, we don't seem to achieve traction.
>
> I would like to know from those who did not persevere,
>
> What got in the way?
>
> Is it all a matter of life intervening?
>
> Are there technical and communication matters that can be addressed to
> remove any barriers that were encountered?
>
> Is there missing information?
>
>  - Dennis
>
>
>
>
> -
> To unsubscribe, e-mail: doc-unsubscr...@openoffice.apache.org
> For additional commands, e-mail: doc-h...@openoffice.apache.org
>
>