DRAFT

Purpose

The purpose of this page is to generate discussion about the User Guide(s) to be developed for Apache OpenOffice or indeed if any should be done at all. Since there has been little or no effort on this aspect of the project Since 2011 or early 2012 I will propose 3 scenarios to start the discussion.

Scenario 1: No Updated Users Guides

We muddle along as we have been. If user ask about documentation we direct them to the out of date v3.3 guides in PDF or ODT format on the OpenOffice.org documentation site http://wiki.openoffice.org/w/images/7/7e/Installation_Guide_OOo3.pdf, http://wiki.openoffice.org/w/images/6/63/Installation_Guide_OOo3.odt,or the even more outdated v3.2 version on the mwiki http://wiki.openoffice.org/wiki/Documentation/OOo3_User_Guides#OpenOffice.org_3.2.

Pro's

  • none that I can see.

Con's

  • Unprofessional
  • Increased possibility of incorrect or out of date information
  • Increased frustration of the user base

Scenario 2: Use ODFAuthors web site to update previous versions of the Getting Started guide.

There are draft chapters for the Getting Started Guide currently at the ODFAuthors website waiting to be reviewed and polished. The major stumbling block to this has been the licensing of the documents. They are currently dual licensed as GPL ver3 and CC-BY ver3. This would require either that we ask legal@ to review the CC-BY version 3 license as to whether it is compatible with the ALV2 (the 2.5 version is already approved) or that we host the distribution of the documents somewhere other than an Apache server.

Pro's

  • Much work already done
  • Possibility to have basic documentation ready for AOO version 3.5 release or shortly thereafter

Con's

  • Licensing issues
    • A JIRA LEGAL issue for acceptance of the CC-BY v3 as a catagory A license was turned down. (SEE:https://issues.apache.org/jira/browse/LEGAL-96
      • We could submit a narrower request allowing us to only host the documents for distribution.
  • Possible distribution issues
    • Can we host them on Apache Controlled Servers?
      • This ties into the License Issue above and also presents bandwidth and space considerations.
    • Host them elsewhere with a link from our website to them.
      • Would need to negotiate with ideally ODFA or some other entity to do this.

Scenario 3: Start from scratch under ALV2 License

I see this more as a long term scenario for AOO 4.0 or beyond. It would solve the licensing and distribution issues, it raises the issue of resources. This would be a major undertaking and require the services of experienced technical writers and editors.

Pro's

  • Solves licensing and distribution problems
  • Allows restructuring of Guides that have grown from there original intent as new features have been added.

Con's

  • Abandons the 3.x line prematurely
  • Can we recruit the experienced people that will be needed or this to be successful
  • No labels

17 Comments

  1. Kay Schenk

    Scenario 1:
    Not really an option but a default. This is what we have now and I have been greatly tempted since the release of 3.4 to link to the draft docs for AOO 3.4 at the ODFAuthors site, but got too busy to bring this up.
    (Additioanlly, all documentation areas on the web server and wiki need realignment).

    Scenario 2. (my preferred option)

    Please elaborate on the "cons" of this option. For example, if work continues with ODFAuthors, where are the docs really hosted? ODFAuthors is already a well-known site for the documents. Can we continue to view this entity as the "official" producer/host of the User Guides and just link/refer people to them? Are we concerned about full control? Why would there be distribution problems.

    Scenario 3:
    Nice, but, why start over when a successful process (ODFAuthors) is already in existence. Additionally, the mechanism for development would need to be determined and maintained,etc.

    1. Keith McKenna

      Kay, I agree completely with your assessment of Scenario 1 as well as ALL the documentation areas needing alignment. I have looked as some of it and the sheer size of the task overwhelms me. We as a project need to think much more deeply about Documentation as a whole and where it fits into the project. My gut feeling is that the general feeling about Documentation ranges from "If we avoid it maybe it will go away" to "It is a necessary evil that hopefully someone else will worry about".

      Scenario 2 is also my preferred option. I will try to elaborate in the document itself on the Cons. Basically they have to do with the license and where they get distributed from. My understanding is that because of license issues they would not be considered "official documentation".

      Scenario 3:
      I agree but I put it there mostly for completion and to get people thinking about what the documentation or AOO v4.x should look like.

    2. RGB.ES

      A good reason to start all over again is to do it differently: ODFAuthors guides are separated by app (Writer, Calc...) which is not wrong by itself, but can be done better if we consider that AOO is a highly integrated suite with lot of stuff in common on all apps.

      IMO, starting from scratch is a lot of work, but also provide lots of opportunities: if done right, it can provide a flexible framework that will make document maintenance more easy.

      I need to think about this a bit more...

      1. Keith McKenna

        I think I understand what you are saying Ricardo and I do not necessarily disagree. My concern with starting over and why I believe t is more an option or AOO 4.0 and beyond is the amount of work and the current lack of resources to accomplish anything for the 3.5 release.

        It definitely a lot of work. The question that I have is can we get the resources that we need to do that large a re-write.

        Also there is nothing that says this cannot be a phased process, indeed that is how I envision it. The first phase being getting something ready or the 3.5 release and also planning what the next iteration should look like.

        I look forward to hearing more of your thoughts on this.

        1. RGB.ES

          I agree with you: it will be really difficult to do this on time for 3.5... but it will be a good "selling point" for 4.0.

          A possibility is to build short documents that show differences between 3.4 and 3.5, a sort of "what's new" and use those document plus the existing ones as transition to the new documentation for 4.0. We can even use those documents to "promote" the 4.0 effort (something like "we are thinking on the future").

          And after all, we are not on a hurry: on my experience providing user support, people tend to use documentation as the last resource to solve a problem.

          1. Keith McKenna

            Only problem with that is that there is no published documentation for 3.4. The whole documentation project got bogged down in the transition period and just after in the license debate. Jean put together all the chapters for a Getting Started Guide on the ODFAuthors web site. They never went anywhere for lack of volunteers for technical review and such.

            It is that Getting Started Guide that I see as the best way of getting any documentation done for the current releases.

            You are all to right on that last statement, but I hate to give them another excuse not to RTFM.

  2. Kay Schenk

    I'm looking at the JIRA issue you posted. It doesn't seem like a negative response to me. In fact, it seems both Shane Curcuru and Sam Ruby as well as Robert Burrell Donkin seemed to want to accept "Creative Commons Attribution 3.0". So, a couple of things:

    • We need to find out from ODFAuthors exactly what version of Creative Commons they are using. I can't tell by looking at the little icon on:

    http://www.odfauthors.org/openoffice.org/images/some-rights/view?searchterm=licensing

    what it is. It doesn't seem to be a current license from this list:

    http://creativecommons.org/licenses/

    • Once we can ascertain the exact nature of the CC license ODFAuthors is using, we should go back to the JIRA ticket.

    Are you in touch with someone at ODFAuthors? If not, I think TJ might be.

    1. Keith McKenna

      Kay;

      The license ODFA uses is a dual license, both GPL 3.0 and Attribution 3.0 Unported (CC BY 3.0) . It was the latter license that the JIRA was written against. The JIRA specifically asked that it be accepted as a Category A license along with the CC-BY v2.5. It was never added to http://www.apache.org/legal/resolved.html#category-a. The hang up was some anti-DRM language in the 3.0 version of the license.

      Yes I am in contact with people there, I am also subscribed to there mail list and do have an account on there server.

      1. Kay Schenk

        OK, since IANAL, I guess I'm not understanding the problems. I'm taking a look at the legal code:

        http://creativecommons.org/licenses/by/3.0/legalcode

        The JIRA tikcet is still open. Maybe we should ask for specific problems? Yeah, I saw the list of category-A acceptable items. None of the CC-BY licenses were on it. GOod that you are keeping up on the ODFAuthors list. I had tried to take a look at an archive quite some time ago, but none was available.

        1. Keith McKenna

          IANAL either, I believe the objection was section 4 subsection a.
          If the ticket is still open I believe that it would be a good idea to ask or specific problems. Can anyone access that system or does it require specific karma? Actually there is one CC-BY license on the list. The Creative Commons Attribution License is CC-BY v2.5. If you click the license name it directs you to the creative Commons summary page showing the license as CC-BY v2.5

          1. Kay Schenk

            You just need to get a JIRA account if you don't have one already.

            https://issues.apache.org/jira/secure/Dashboard.jspa

            and sign up

            The ticket is still open, so once your account is setup up, just go to it, and comment away!

            Go for it! :)

        2. Dennis E. Hamilton

          There seem to be more places where reviewed licenses are listed.

          It seems that older CC-by licenses also have a form of the anti-DRM statement. However, it does not prevent DRM-ed delivery, it simply essentially requires that the availability of non-DRM-ed versions always be stated and the means for obtaining them be specified.

          A safe way to deal with this might be to assume Category B and not deliver editable or DRM-ed forms via ASF sites.

          So long as the work is continued on ODFAuthors, this question does not have to be answered. If authoring were brought inside the project, and derivatives of the ODFAuthors work are produced there, that does become an issue.

          The expedient approach may be to simply stay on ODFAuthors. That allows some cross-pollination among the guides for different openoffice-lineage products to the extent that remains useful.

    2. Dennis E. Hamilton

      @Kay,

      It is necessary to look at the documents themselves to see what the licenses are.

      I think, because of the dual licensing, the preferable case would be to have the editable forms of the documents (i.e., essentially the "source") retained on the ODFAuthors site (with a contingency plan, such as SourceForge backups, in case that site is ever closed).

      The PDFs could be posted on openoffice.org or elsewhere, since that is not "source code." In that case, it would be appropriate to ensure that the documents include links to where they are found in their other forms on ODFAuthors. That is a good idea anyway. It is the best way for folks to find out about older and newer versions, submit changes and improvements, and contribute to the authoring of more.

      There are print versions available via ODFAuthors at times, and any sales/royalties for those go somewhere. I suspect that is fine, especially if it helps the ODFAuthors site keep operating.

      1. Kay Schenk

        @Dennis, re: dual licensing

        Yes, I figured that out after a bit, but have not reviewed the individual docs. We are primarily concerned with the drafts of the 3.4 User Guide at the moment.

        This is what they say--

        This document is Copyright © 2012 by its contributors as listed below. You may distribute it and/or modify it under the terms of either the GNU General Public License, version 3 or later (http://www.gnu.org/licenses/gpl.html), or the Creative Commons Attribution License, version 3.0 or later (http://creativecommons.org/licenses/by/3.0/).

        On your other statement re simply posting and not hosting. That is what I had thought as well, but there is apparently some concern with this, that the docs would not be considered "official" etc. I can not address this statement, really.

        At this point, I am mostly playing the role of the interested by stander as I believe Keith has the lead on this.

        1. Dennis E. Hamilton

          Yes, I also have no idea what "official" means in this context. It is inconceivable that putting these through something like AOO release management would add anything useful. I suppose it means we'd take bugs in the bugzilla and manage errata somehow.

          I am going to ignore officialness on the basis that what ODFAUthors provides is good enough, so long as there is active maintenance and contribution there. That seems like a superior starting point.

          1. Keith McKenna

            @Kay and Dennis;

            I believe the issue around them being "official" docs was raised early on the dev list around the 2011 time frame and had to do with them not being ALv2 licensed and on server not controlled by the project.

            One issue that was raised in the earlier conversations was the issue of cover art or the docs. Would we have to get formal permission to use trademarked items such as the gulls?

            I agree that using a process such as the AOO Release Management one only adds a level of bureaucracy and adds nothing useful to them.

            To that end I have posted request or lazy consensus in the thread on the dev list to expire Tuesday September 26 at 05:45 UTC.

  3. Dennis E. Hamilton

    I've previously indicated that I prefer Option 2 also.

    Although I feel a bit awkward working on a dual-licensed document where I have no interest in the LGPL case, only the CC-BY case.

    I can manage to deal with that in any contributions I make to ODFAuthors works.

    I think there are other reasons to stay on ODFAuthors.

    First, it continues to honor and build on the contribution that ODFAuthors and those works represent.

    Secondly, it is not clear to me how clean the provenance of those documents happens to be. That matters if continuation work is brought under an ASF project. Continuing contribution on ODFAuthrs there doesn't make the provenance any worse. It does avoid having to deal with questions about the provenance.

    On the other hand, I have to remind myself that it is unwise to fork any of those documents outside of ODFAuthors, even if I have contributed significant content to any of them. I can, of course, fork my own contribution wherever I like, but only that contribution. At this point, that's pretty hypothetical because I have failed to make any contribution to the documentation. I am keeping the option open, though.