FW: Can we get this started again?

[Dennis E. Hamilton]

OK, I understand.  Forwarding.

Thank you for the reply.

 - Dennis

PS: I finally did get my hands on a LibreOffice T-Shirt at OSCON 2014.  I still 
admire your plain one best.

> -Original Message-
> From: Jean Weber [mailto:jeanwe...@gmail.com]
> Sent: Thursday, January 21, 2016 02:55
> To: orc...@apache.org
> Subject: Re: Can we get this started again?
> 
> I was not suggesting working on a common shared product. I have no
> interest in attempting to produce docs that could be used by both
> projects. I know how to do files that could work, but my experience with
> volunteers suggests they would not cope with them.
> 
> 
> TDF will soon be announcing a new mentor/lead for the documentation
> team. I don't know what direction the team will choose to take: whether
> it will include user guides in their current form or not.
> 
> 
> I am no longer subscribed to the AOO Docs list. You may forward this
> note there if you wish.
> 
> Regards, Jean
> 
> On Thursday, January 21, 2016, Dennis E. Hamilton   > wrote:
> 
> 
>   Hello Jean,
> 
>   I recently noticed your 2015-12-08 comment to doc@ oo.a.o,
> 
>   If it's any consolation, work on user documentation at
> LibreOffice
>   is also stalled, due to lack of participants, ... .
> 
>   I'd like to see everyone interested in user docs coming over to
>   LibreOffice and working there with a larger community.
> 
>   It would certainly be useful to avoid redundant effort.  I'm not
> clear how the results of shared work could be employed with ease by both
> projects though.
> 
>   There are book-form guides to LibreOffice (and I have a set), that
> strike me as an outgrowth of what was originally the ODF Authors work.
> Is that still the thrust?
> 
>   As you know, there has been no traction to continue the equivalent
> for AOO on ODF Authors.  The current AOO effort seems focused on an on-
> line, wiki-form approach using a structure begun in January 2013 and
> worked on piecemeal since.
> 
>   What would you see as a common shared product repurposed for the
> two products?  Or would you attempt to cover the common parts in a way
> that worked for both?
> 
>   I am curious what your thinking might be.
> 
>   And Happy New Year!
> 
>-- Dennis E. Hamilton
>   orc...@apache.org 
>   dennis.hamil...@acm.org  +1-206-779-9430
>   https://keybase.io/orcmid  PGP F96E 89FF D456 628A
>   X.509 certs used and requested for signed e-mail
> 
> 
> 



-
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: New Volunteer - Technical Writing Experience

[Keith N. McKenna]

Jessica Steel wrote:
> Hi Keith,
> 
> I have completed an edit/proofread and light re-write of Automatic
> Options. If all is well I will start on Support File Formats.
> 
> Thanks,
> 
> Jess
> 
> 
> On 21 January 2016 at 01:10, Keith N. McKenna  
> wrote:
>> Jessica Steel wrote:
>>> Hi Keith,
>>>
>>> I am happy to work on the Auto correct and Support File Formats if that 
>>> suits?
>>>
>>> Thanks,
>>> Jess
>>>
>>> On 19 January 2016 at 01:30, Keith N. McKenna  
>>> wrote:
 Jessica Steel wrote:
> Hello,
>
> I have set up a login and read the contributions page and I am
> currently working my way into the user guide. Please let me know where
> to begin or how I can be of assistance. As I do not know the project
> yet I am most interested in anything that can gain me practical
> experience in technical writing, be it manuals, software application
> instructions, user guides, or even basic documentation: I am at your
> disposal.
>
> Thanks,
>
> Jessica
>
 Jessica;
 We use a status page to track where we are with the User guide.It is at
 https://wiki.openoffice.org/wiki/Documentation/UserGuide/Status. Take a
 look at the entries for the Introductory material and for the Writer
 User Guide. Any that need proofreading or are not finished, go ahead and
 work on them. Although it say proofreading, it really is more and editor
 function. Re-writing for clarity and grammar if needed, as well as style
 etc. Whatever that you do please add your signature to it. If you are
 writing it or extending it add your sig by typing `~~~ in the author
 slot, or if you ahve proofed it add your sig after proffreading by
 typing ~ (5 tildes) this will add your Signature and a date/time
 stamp. Just let the list know wht you are going to be working on so we
 do not step on each others toes.

 Two documents you will want to refer to extensively are the Guide to
 Editing Guide at
 https://wiki.openoffice.org/wiki/Documentation/Dashboard/Wiki_Editing_Policy,
 and the Style Guide  at
 https://wiki.openoffice.org/wiki/Documentation/Dashboard/Help_Style_Guide.

 Regards
 Keith
> On 14 January 2016 at 02:19, Keith N. McKenna  
> wrote:
>> Jessica Steel wrote:
>>> Hello again,
>>>
>>> Thank you for responding. I would like to request an Mwiki account
>>> using this email address and my user name as jessicajsteel.
>>>
>>> I will gladly take a look at the links you have provided, and I also
>>> look forward to be part of this project.
>>>
>>> Thanks again for the quick response.
>>>
>>> Regards,
>>>
>>> Jessica
>>>
>>> On 12 January 2016 at 13:06, Keith N. McKenna 
>>>  wrote:
 Jessica Steel wrote:
> Hello,
>
> I am an Australian who would like to be a volunteer. I have a Bachelor
> in Writing and I have
> just completed a Certificate in Technical Writing as well. I am now
> seeking to gain some work experience in technical writing with Apache.
>
> I have read through the Orientation Modules and subscribed to this
> mailing list. Any guidance or advice would be much appreciated.
>
> Regards,
>
> Jessica
>
 Jessica;

 Welcome to the OpenOffice documentation team. Currently we are working
 on trying to get the introductory material and the Writers Guide
 sections of the User Guide completed and released. To help with these
 tasks you will need an account on our Media Wiki(Mwiki). To request an
 account send an e-mail to this list requesting an Mwiki account an
 include your preferred user name, e-mail address and one of our admins
 will create it. In the mean time I would suggest you peruse the
 following: https://wiki.openoffice.org/wiki/Documentation/Contribute.
 Some of the information is a bit dated, but still much is useful.
 Also you can peruse the user guide at
 https://wiki.openoffice.org/wiki/Documentation/UserGuide to see how it
 is organized and what you might like to start on.

 Once your account is done and you are ready to start working, come back
 to the list and let us know and we will get you started.

 Again welcome and I look forward to working with you.

 Regards
 Keith McKenna


>> Jessica;
>>
>> Your mwiki account jessicajsteel has been created. You will receive an
>> separate e-mail at this address with a temporary password that should be
>> changed at first login.
>>
>> Regards
>> Keith
>>


>> Jessica;
>>
>> That would be great. When you 

Re: New Volunteer - Technical Writing Experience

[Jessica Steel]

Hi Keith,

I have done as requested though my name did not show up on the main
status page. I'm not overly concerned but I just thought I should
mention it. I will commence work on Support File Formats shortly.

Thanks for your guidance!

Jess

On 22 January 2016 at 11:22, Keith N. McKenna  wrote:
> Jessica Steel wrote:
>> Hi Keith,
>>
>> I have completed an edit/proofread and light re-write of Automatic
>> Options. If all is well I will start on Support File Formats.
>>
>> Thanks,
>>
>> Jess
>>
>>
>> On 21 January 2016 at 01:10, Keith N. McKenna  
>> wrote:
>>> Jessica Steel wrote:
 Hi Keith,

 I am happy to work on the Auto correct and Support File Formats if that 
 suits?

 Thanks,
 Jess

 On 19 January 2016 at 01:30, Keith N. McKenna  
 wrote:
> Jessica Steel wrote:
>> Hello,
>>
>> I have set up a login and read the contributions page and I am
>> currently working my way into the user guide. Please let me know where
>> to begin or how I can be of assistance. As I do not know the project
>> yet I am most interested in anything that can gain me practical
>> experience in technical writing, be it manuals, software application
>> instructions, user guides, or even basic documentation: I am at your
>> disposal.
>>
>> Thanks,
>>
>> Jessica
>>
> Jessica;
> We use a status page to track where we are with the User guide.It is at
> https://wiki.openoffice.org/wiki/Documentation/UserGuide/Status. Take a
> look at the entries for the Introductory material and for the Writer
> User Guide. Any that need proofreading or are not finished, go ahead and
> work on them. Although it say proofreading, it really is more and editor
> function. Re-writing for clarity and grammar if needed, as well as style
> etc. Whatever that you do please add your signature to it. If you are
> writing it or extending it add your sig by typing `~~~ in the author
> slot, or if you ahve proofed it add your sig after proffreading by
> typing ~ (5 tildes) this will add your Signature and a date/time
> stamp. Just let the list know wht you are going to be working on so we
> do not step on each others toes.
>
> Two documents you will want to refer to extensively are the Guide to
> Editing Guide at
> https://wiki.openoffice.org/wiki/Documentation/Dashboard/Wiki_Editing_Policy,
> and the Style Guide  at
> https://wiki.openoffice.org/wiki/Documentation/Dashboard/Help_Style_Guide.
>
> Regards
> Keith
>> On 14 January 2016 at 02:19, Keith N. McKenna 
>>  wrote:
>>> Jessica Steel wrote:
 Hello again,

 Thank you for responding. I would like to request an Mwiki account
 using this email address and my user name as jessicajsteel.

 I will gladly take a look at the links you have provided, and I also
 look forward to be part of this project.

 Thanks again for the quick response.

 Regards,

 Jessica

 On 12 January 2016 at 13:06, Keith N. McKenna 
  wrote:
> Jessica Steel wrote:
>> Hello,
>>
>> I am an Australian who would like to be a volunteer. I have a 
>> Bachelor
>> in Writing and I have
>> just completed a Certificate in Technical Writing as well. I am now
>> seeking to gain some work experience in technical writing with 
>> Apache.
>>
>> I have read through the Orientation Modules and subscribed to this
>> mailing list. Any guidance or advice would be much appreciated.
>>
>> Regards,
>>
>> Jessica
>>
> Jessica;
>
> Welcome to the OpenOffice documentation team. Currently we are working
> on trying to get the introductory material and the Writers Guide
> sections of the User Guide completed and released. To help with these
> tasks you will need an account on our Media Wiki(Mwiki). To request an
> account send an e-mail to this list requesting an Mwiki account an
> include your preferred user name, e-mail address and one of our admins
> will create it. In the mean time I would suggest you peruse the
> following: https://wiki.openoffice.org/wiki/Documentation/Contribute.
> Some of the information is a bit dated, but still much is useful.
> Also you can peruse the user guide at
> https://wiki.openoffice.org/wiki/Documentation/UserGuide to see how it
> is organized and what you might like to start on.
>
> Once your account is done and you are ready to start working, come 
> back
> to the list and let us know and we will 

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