Using GitHub as a platform for creating documentation and publications

[Dennis Hamilton <or...@msn.com>]

Something that might be helpful to consider is the fact that Microsoft is moving all of its on-line developer documentation (that is, for developers and IT administrators as users) to GitHub: <https://github.com/MicrosoftDocs>.  This is a gigantic project.

Although MicrosoftDocs usage is specific to Microsoft and there seems to be some custom tooling, there is also some attention to on-ramping: 
<https://github.com/MicrosoftDocs/microsoft-365-community/wiki/Getting-Started>.  (This takes advantage of GitHub having wikis available for every project.)

Note that the MicrosoftDocs customized use of GitHub is for production of on-line documentation.  I am not urging their model, just pointing that there may be information that is adaptable for Apache/openoffice-docs on GitHub.

I have been thinking of Document Engineering as a methodology around production of digital publications, web content, etc.  I've started a project on that subject at <https://github.com/orcmid/docEng>.  This will focus on writing-in-the-open on collaborative document-engineering with GitHub as the platform.  This is completely separate from the openoffice-docs efforts and I will say no more about it here.  It is not about producing AOO docs, but some of the tutorial materials may be helpful to those who want to author, edit, or review openoffice-docs contributions.

 - Dennis

-----Original Message-----
From: Dennis Hamilton 
Sent: Friday, February 12, 2021 08:09
To: doc@openoffice.apache.org
Subject: RE: GNU Linux install guide - 6 pages....

Marcia, I agree that the governance, workflow, and review requirements for the AOOdocs effort need to be established and made clear.  I also agree that making onboarding simple and establishing how to work with GitHub as a place for a documentation project is challenging.

I also must point out, in-line below, that openoffice-uni.org has nothing to do with openoffice.org and, in particular, the Apache OpenOffice project.  

Marcia, I am unclear where you provided the GNU Linux install guide.  Is it available for download?

"PEER REVIEW" OR NOT

Although there are mechanisms with regard to Apache project source code and the development of releases, these are known mainly by the developers. The software development approach does provide for *authorized* committers to commit materials and changes first, having "peer review" review second (where peers are mainly *authorized* committers).  But moving to a "release" state takes more than that, including public review periods.  

A relevant example with regard to apache/openoffice-docs is that GitHub user DiGro has been granted contributor rights, as you can see on the openoffice-docs home page: https://github.com/apache/openoffice-docs .  Previously, I think this was for FJCC.  So there is now an issue about anonymity.  You can see from https://github.com/apache/openoffice-docs/tree/Getting-Sarted-Guide/Review that FJCC was able to commit changes directly.  The second column in that list identifies what the "commit message" was for the latest (sometimes only) action with regard to those files.  The last column indicates how ling it has been since that occurred.

For openoffice-docs, Keith is essentially lead developer, at least until governance and on-boarding are smoothed out.  I have no idea about the appearance of DiGro as a contributor in the place of FJCC who we knew to be Francis.  

 - Dennis


-----Original Message-----
From: marcia wilbur <ai...@well.com>
Sent: Tuesday, February 9, 2021 19:18
To: doc@openoffice.apache.org
Cc: dev@openoffice.apache.org
Subject: GNU Linux install guide - 6 pages....

Hi. 

I realize I did prematurely create a simple installation guide for GNU Linux users without realizing the licensure. 
This could be fixed. 
However, I received an email off this list from Keith stating the guide was not peer reviewed. 

I wonder, were these guides?
[orcmid about USAGE OF APACHE AND AOO MARKS AND TRADEMARKS] http://openoffice-uni.org/ [end orcmid] this was also posted online. 
[orcmid]
Openoffice-uni.org is not part of either openoffice.org or the Apache OpenOffice Project.
Note this statement buried at the bottom of the page: "This website is not affiliated with the Apache Software Foundation."
I do not know whether this site is in conformance with Apache Software Foundation trademark requirements.  That is a matter for the Apache OpenOffice Project Management Committee (PMC) to determine.  I have no insight into any deliberations the PMC may have had about this site.

The question about peer-reviewing of documents provided via openoffice-uni.org is not relevant to the AOOdocs effort.
Marcia, if you want to self-publish documents, you are free to do so.  Just do not imply that those are products of the Apache OpenOffice project and do not use marks of the Apache Software Foundation and Apache OpenOffice that imply any association.

This is not a comment on the worthiness of the openoffice-uni.org to provide materials for students.  It is about the appearance of association with the Apache OpenOffice Project.  Disclaimers in the "fine print" to not compensate for that, in my opinion.
[end orcmid]

One recommendation - please make the onboarding simple and straightforward for those volunteering in this effort for documentation.

I was just trying to be a positive force and influence for this project, but really and am disappointed by the docs team - well, particularly and the continued push to use the old docs, mix method of documentation and as I heard during fosdem = the idea... this project cannot move forward as a current offering - like a corporation

I do encourage the docs team to move forward with current useful documentation for the project, working with developers in an effort to drive innovation.

I hope you can move forward with these attitudes in a positive manner.

Keith, all future communication should be made here.

Thank you.



 


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


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