On 03/12/2019 03:52 AM, Justin W. Flory wrote:

On 3/11/19 5:37 PM, Matthew Miller wrote:

...

This seems like it has potential!

https://opensource.googleblog.com/2019/03/introducing-season-of-docs.html

My personal suggestion is to wait for the program to mature before volunteering Fedora.

I am skeptical. My first impression is it is a technical writing certification program from Google, and open source projects act as volunteer certificate proctors.

There was a long discussion about this on the Google GSoC mailing list. A key difference of Season of Docs is technical writers are not paid. This excludes a group of people in most need for professional experience and mentorship. It also sends an implied message about the value of technical writing; Season of Docs is the only Google open source program (to my knowledge) without a stipend or compensation of time (GSoC with paid stipend, GCI with sponsored trip to Google HQ).

My first impression was not boarding the bandwagon yet and observing how the program matures first. I would like equal treatment for technical writing and development work before endorsing the program.

My intention is not to be pessimistic, but I am disappointed this feedback seems unaccounted for in how Season of Docs is currently described and promoted.

Hi Justin,

Maybe the conditions have changed since you first learned about the program. The FAQ [1] says:

"Is Season of Docs considered an internship, a job, or any form of employment?"

Season of Docs is an activity that the technical writer performs as an independent technical writer for which they are paid a stipend. Technical writers may choose to opt out of receiving the stipend."

and:

"Will I be paid for participating in Season of Docs?

Yes. Google will provide a stipend to those technical writers who successfully complete the program. You can choose to opt out of receiving the stipend."

So, maybe we could give it a thought.

Regards, Robert

On 3/12/19 11:54 AM, Brian (bex) Exelbierd wrote:

On Tue, Mar 12, 2019 at 9:35 AM Robert Kratky <rkratky@gmail.com mailto:rkratky@gmail.com> wrote:

On 03/12/2019 03:52 AM, Justin W. Flory wrote:
> On 3/11/19 5:37 PM, Matthew Miller wrote:
>> This seems like it has potential!
>>
>>
https://opensource.googleblog.com/2019/03/introducing-season-of-docs.html
>>
>
> My personal suggestion is to wait for the program to mature before
> volunteering Fedora.

My primary concern is having mentoring support and a well identified set of tasks.  If Petr Bokoc can take charge here then I think we can be successful.  I suspect that, at a minimum, we could have someone come in and do things like refactor the installation guide by edition or review and update docs for the current release.  We should, imho, make sure this person focuses on F30, not F29 as that is what should be current for most if not all of the cycle.

I am happy to coordinate our application and work with Petr to get it done.

That's my concern as well. Is there anyone here who has experience with GSoC? I know Fedora participated before and I'm wondering about how much commitment an internship like that requires - how much coaching, task tracking, that kind of stuff. Bex, were you involved with that, or do you know who was?

I'm also concerned that any tech writer will need to interact with the wider community, not just us here in docs - someone needs to give them info and preferably do technical reviews as well. We'll need to make sure any relevant engineering people can (and want to) do that if we go forward with this. In case of the install guide I'm worried that the team is basically all Red Hatters and they'll be too busy doing their normal work, but OTOH getting Red Hat engineers to work with us could be easier than making sure someone from the community who only contributes as a hobby will be available for significant amounts of time... I dunno.

regards,

bex

>
> I am skeptical. My first impression is it is a technical writing
> certification program from Google, and open source projects act as
> volunteer certificate proctors.
>
> There was a long discussion about this on the Google GSoC
mailing list.
> A key difference of Season of Docs is technical writers are not
paid.
> This excludes a group of people in most need for professional
experience
> and mentorship. It also sends an implied message about the value of
> technical writing; Season of Docs is the only Google open source
program
> (to my knowledge) without a stipend or compensation of time
(GSoC with
> paid stipend, GCI with sponsored trip to Google HQ).
>
> My first impression was not boarding the bandwagon yet and
observing how
> the program matures first. I would like equal treatment for
technical
> writing and development work before endorsing the program.
>
> My intention is not to be pessimistic, but I am disappointed this
> feedback seems unaccounted for in how Season of Docs is currently
> described and promoted.

Hi Justin,

Maybe the conditions have changed since you first learned about
the program. The FAQ [1] says:

"Is Season of Docs considered an internship, a job, or any form of
employment?"

Season of Docs is an activity that the technical writer performs
as an independent technical writer for which they are paid a
stipend. Technical writers may choose to opt out of receiving the
stipend."

and:

"Will I be paid for participating in Season of Docs?

Yes. Google will provide a stipend to those technical writers who
successfully complete the program. You can choose to opt out of
receiving the stipend."

So, maybe we could give it a thought.

Regards,
Robert
_______________________________________________
docs mailing list -- docs@lists.fedoraproject.org
<mailto:docs@lists.fedoraproject.org>
To unsubscribe send an email to docs-leave@lists.fedoraproject.org
<mailto:docs-leave@lists.fedoraproject.org>
Fedora Code of Conduct: https://getfedora.org/code-of-conduct.html
List Guidelines:
https://fedoraproject.org/wiki/Mailing_list_guidelines
List Archives:
https://lists.fedoraproject.org/archives/list/docs@lists.fedoraproject.org

-- Brian (bex) Exelbierd | bexelbie@redhat.com mailto:bexelbie@redhat.com | bex@pobox.com mailto:bex@pobox.com Fedora Community Action & Impact Coordinator @bexelbie | http://www.winglemeyer.org

---

docs mailing list -- docs@lists.fedoraproject.org To unsubscribe send an email to docs-leave@lists.fedoraproject.org Fedora Code of Conduct: https://getfedora.org/code-of-conduct.html List Guidelines: https://fedoraproject.org/wiki/Mailing_list_guidelines List Archives: https://lists.fedoraproject.org/archives/list/docs@lists.fedoraproject.org

My 78 year old opinion with 55plus years of experience. I started documentation projects with gdoc (IBM 360 days), and later I worked with various static command line documentation software tools  such as asciidoc, latex, etc. In the end, these command line tools all failed. What did work, was using collaboration tools built into graphical WYSIWYG tools. These tools, MS office, LibreOffice, WPS, other opensource and non gpl3 software, coupled with git repositories, worked efficiently giving the very best results and deliverable on time and at minimal cost. Direct output from WYSIWYG could allow a user to printed a file, or to download a pdf.

Every college/university student or other, learned MSoffice or Openoffice or LibreOffice. This is what they use  to submit reports or technical papers for publication or to his/her professor. In industry, we used one of the mentioned WYSIWYG tools to do collaboration. These tools support multi-user collaboration, multi-user markups, multi-user comments and master/chapter documents.  The author of the "section" could accept/reject or further modify changes and add comments. These tools also can generate tables of contents, indexes. It is great for rapid "desktop" publishing.

In my 55+ years of experience, when the only tool you have is a hammer, everything looks like a nail.   If you have Latex, then you only accept Latex input. If you have asciidoc, you only accept asciidoc input.

My Rant,  Where is F29 documentation?  What happened to it's sparsity?  Is asciidoc a tool used by recent graduates or others. We learn to use emails which are WYSIWYG and we submit proposals the same way.

How many iterations of asciidoc generation followed by minor edits does it take to obtain a clean document section?   Who has time for command line work that takes 10x more effort to produce a clean output?  Check the git log. How many iterations of an asciidoc source and update to a git repository did it take to get one section right?  And what about spellcheck? I did not see any asciidoc spellcheck or grammar tools.  Recently I saw advertisements for Gramarly. Gramarly is a non FOSS WYSIWYG tool to check spelling, sentence construction and syntax.  Together, with WYSIWYG, what would result is a great reduction of work to produce a more accurate document, and to deliver it on time.

In one shop I worked  with msoffice. It was used to produce html output.  We can do the same work with LibreOffice.  If asciidoc is an absolute requirement, why not evaluate a  WYSIWYG open source LibreOffice output to HTML and HTML to asciidoc? WYSIWYG output allows a master document organization as follows:

Master=Document     include  section  1     ==> chapter 1..3 document     include section  2       ==> chapter 4 document     .......     include Chapter n       ==>  chapter n-end document

I see myself as the tail that is trying to shake up the dog. And since I am not able to get others to overcome this hammer/nail situation, I bowed out. I am now only an observer to the Documentation project.

My Disappointment with the Documentation Project. Using WYSIWYG, I spend two hundred hours correcting the Fedora 28 documentation. I corrected the grammar, corrected the accuracy, included omissions, and removed  non-relevant documentation,  and emailed it to the documentation group. it's gone. It became file13 virtual ware.

My idea. If you want someone to contribute to documentation, they should be able to write as easily as I am doing, using this email interface. and then ultimately, if you have to, you convert their GUI output to the static asciidoc command line tool format.

Anyone within Fedora wanting to do a WYSIWYG release notes project in parallel with using asciidoc?  Let me know. You may have me interested to contribute.

Regards  Leslie Leslie Satenstein Montréal Québec, Canada

On Thursday, March 14, 2019, 11:41:56 a.m. EDT, Brian (bex) Exelbierd bexelbie@redhat.com wrote:

On Thu, Mar 14, 2019 at 4:18 PM Petr Bokoc pbokoc@redhat.com wrote:

On 3/12/19 11:54 AM, Brian (bex) Exelbierd wrote:

On Tue, Mar 12, 2019 at 9:35 AM Robert Kratky rkratky@gmail.com wrote:

...

On 03/12/2019 03:52 AM, Justin W. Flory wrote:

...

On 3/11/19 5:37 PM, Matthew Miller wrote:

...

This seems like it has potential!

https://opensource.googleblog.com/2019/03/introducing-season-of-docs.html

My personal suggestion is to wait for the program to mature before volunteering Fedora.

My primary concern is having mentoring support and a well identified set of tasks.  If Petr Bokoc can take charge here then I think we can be successful.  I suspect that, at a minimum, we could have someone come in and do things like refactor the installation guide by edition or review and update docs for the current release.  We should, imho, make sure this person focuses on F30, not F29 as that is what should be current for most if not all of the cycle.

I am happy to coordinate our application and work with Petr to get it done.

That's my concern as well. Is there anyone here who has experience with GSoC? I know Fedora participated before and I'm wondering about how much commitment an internship like that requires - how much coaching, task tracking, that kind of stuff. Bex, were you involved with that, or do you know who was?

I am happy to serve as the coordinator, as I do (with help) for GSoC and GCI.  The part I think we need an owner for is tracking tasks and mentoring.  I haven't reviewed the details, but I presume 2-4 hours a week at the beginning and less near the end.

I'm also concerned that any tech writer will need to interact with the wider community, not just us here in docs - someone needs to give them info and preferably do technical reviews as well. We'll need to make sure any relevant engineering people can (and want to) do that if we go forward with this. In case of the install guide I'm worried that the team is basically all Red Hatters and they'll be too busy doing their normal work, but OTOH getting Red Hat engineers to work with us could be easier than making sure someone from the community who only contributes as a hobby will be available for significant amounts of time... I dunno.

This needs to be defined by scope.  I wonder if maybe we should focus on modularity or another initiative area first.  We could also ask for docs on contributing to docs and translations to help us build a bootstrap.

regards,

bex

regards,

bex

...

...

I am skeptical. My first impression is it is a technical writing certification program from Google, and open source projects act as volunteer certificate proctors.

There was a long discussion about this on the Google GSoC mailing list. A key difference of Season of Docs is technical writers are not paid. This excludes a group of people in most need for professional experience and mentorship. It also sends an implied message about the value of technical writing; Season of Docs is the only Google open source program (to my knowledge) without a stipend or compensation of time (GSoC with paid stipend, GCI with sponsored trip to Google HQ).

My first impression was not boarding the bandwagon yet and observing how the program matures first. I would like equal treatment for technical writing and development work before endorsing the program.

My intention is not to be pessimistic, but I am disappointed this feedback seems unaccounted for in how Season of Docs is currently described and promoted.

Hi Justin,

Maybe the conditions have changed since you first learned about the program. The FAQ [1] says:

"Is Season of Docs considered an internship, a job, or any form of employment?"

Season of Docs is an activity that the technical writer performs as an independent technical writer for which they are paid a stipend. Technical writers may choose to opt out of receiving the stipend."

and:

"Will I be paid for participating in Season of Docs?

Yes. Google will provide a stipend to those technical writers who successfully complete the program. You can choose to opt out of receiving the stipend."

So, maybe we could give it a thought.

Regards, Robert _______________________________________________ docs mailing list -- docs@lists.fedoraproject.org To unsubscribe send an email to docs-leave@lists.fedoraproject.org Fedora Code of Conduct: https://getfedora.org/code-of-conduct.html List Guidelines: https://fedoraproject.org/wiki/Mailing_list_guidelines List Archives: https://lists.fedoraproject.org/archives/list/docs@lists.fedoraproject.org

-- Brian (bex) Exelbierd | bexelbie@redhat.com | bex@pobox.com Fedora Community Action & Impact Coordinator @bexelbie | http://www.winglemeyer.org

---

docs mailing list -- docs@lists.fedoraproject.org To unsubscribe send an email to docs-leave@lists.fedoraproject.org Fedora Code of Conduct: https://getfedora.org/code-of-conduct.html List Guidelines: https://fedoraproject.org/wiki/Mailing_list_guidelines List Archives: https://lists.fedoraproject.org/archives/list/docs@lists.fedoraproject.org

-- Petr Bokoc (irc: pbokoc) Technical Writer Engineering Content Services

Red Hat Czech, s. r. o. Purkynova 99 612 45 Brno, Czech Republic

---

docs mailing list -- docs@lists.fedoraproject.org To unsubscribe send an email to docs-leave@lists.fedoraproject.org Fedora Code of Conduct: https://getfedora.org/code-of-conduct.html List Guidelines: https://fedoraproject.org/wiki/Mailing_list_guidelines List Archives: https://lists.fedoraproject.org/archives/list/docs@lists.fedoraproject.org

On Thu, 2019-03-14 at 16:17 +0100, Petr Bokoc wrote:

That's my concern as well. Is there anyone here who has experience with GSoC? I know Fedora participated before and I'm wondering about how much commitment an internship like that requires - how much coaching, task tracking, that kind of stuff. Bex, were you involved with that, or do you know who was?

I've mentored in GNOME for both GSoC and OPW (Outreach Program for Women, the precursor to Outreachy). For OPW, I've mentored docs internships. The time commitment varied quite a bit from person to person. I think what's more important than how much time you spend mentoring is how often that time is spent. You can't just frontload a week with a three-hour meeting and go offline.

I'm also concerned that any tech writer will need to interact with the wider community, not just us here in docs - someone needs to give them info and preferably do technical reviews as well. We'll need to make sure any relevant engineering people can (and want to) do that if we go forward with this. In case of the install guide I'm worried that the team is basically all Red Hatters and they'll be too busy doing their normal work, but OTOH getting Red Hat engineers to work with us could be easier than making sure someone from the community who only contributes as a hobby will be available for significant amounts of time... I dunno.

I'm happy to help in whatever way I can, whether that's dealing with the application process, extracting information from engineers' brains, or actually taking on a mentorship role.

-- Shaun