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
Leslie Satenstein
Montréal Québec, Canada
On Thursday, March 14, 2019, 11:41:56 a.m. EDT, Brian (bex) Exelbierd <bexelbie@xxxxxxxxxx> wrote:
On Thu, Mar 14, 2019 at 4:18 PM Petr Bokoc <pbokoc@xxxxxxxxxx> wrote:
>
> On 3/12/19 11:54 AM, Brian (bex) Exelbierd wrote:
>
>
>
> On Tue, Mar 12, 2019 at 9:35 AM Robert Kratky <rkratky@xxxxxxxxx> 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@xxxxxxxxxxxxxxxxxxxxxxx
>> To unsubscribe send an email to docs-leave@xxxxxxxxxxxxxxxxxxxxxxx
>> 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@xxxxxxxxxxxxxxxxxxxxxxx
>
> --
> Brian (bex) Exelbierd | bexelbie@xxxxxxxxxx | bex@xxxxxxxxx
> Fedora Community Action & Impact Coordinator
> @bexelbie | http://www.winglemeyer.org
>
> _______________________________________________
> docs mailing list -- docs@xxxxxxxxxxxxxxxxxxxxxxx
> To unsubscribe send an email to docs-leave@xxxxxxxxxxxxxxxxxxxxxxx
> 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@xxxxxxxxxxxxxxxxxxxxxxx
>
> --
> 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@xxxxxxxxxxxxxxxxxxxxxxx
> To unsubscribe send an email to docs-leave@xxxxxxxxxxxxxxxxxxxxxxx
> 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@xxxxxxxxxxxxxxxxxxxxxxx
--
Brian (bex) Exelbierd | bexelbie@xxxxxxxxxx | bex@xxxxxxxxx
Fedora Community Action & Impact Coordinator
@bexelbie | http://www.winglemeyer.org
_______________________________________________
docs mailing list -- docs@xxxxxxxxxxxxxxxxxxxxxxx
To unsubscribe send an email to docs-leave@xxxxxxxxxxxxxxxxxxxxxxx
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@xxxxxxxxxxxxxxxxxxxxxxx
>
> On 3/12/19 11:54 AM, Brian (bex) Exelbierd wrote:
>
>
>
> On Tue, Mar 12, 2019 at 9:35 AM Robert Kratky <rkratky@xxxxxxxxx> 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@xxxxxxxxxxxxxxxxxxxxxxx
>> To unsubscribe send an email to docs-leave@xxxxxxxxxxxxxxxxxxxxxxx
>> 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@xxxxxxxxxxxxxxxxxxxxxxx
>
> --
> Brian (bex) Exelbierd | bexelbie@xxxxxxxxxx | bex@xxxxxxxxx
> Fedora Community Action & Impact Coordinator
> @bexelbie | http://www.winglemeyer.org
>
> _______________________________________________
> docs mailing list -- docs@xxxxxxxxxxxxxxxxxxxxxxx
> To unsubscribe send an email to docs-leave@xxxxxxxxxxxxxxxxxxxxxxx
> 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@xxxxxxxxxxxxxxxxxxxxxxx
>
> --
> 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@xxxxxxxxxxxxxxxxxxxxxxx
> To unsubscribe send an email to docs-leave@xxxxxxxxxxxxxxxxxxxxxxx
> 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@xxxxxxxxxxxxxxxxxxxxxxx
--
Brian (bex) Exelbierd | bexelbie@xxxxxxxxxx | bex@xxxxxxxxx
Fedora Community Action & Impact Coordinator
@bexelbie | http://www.winglemeyer.org
_______________________________________________
docs mailing list -- docs@xxxxxxxxxxxxxxxxxxxxxxx
To unsubscribe send an email to docs-leave@xxxxxxxxxxxxxxxxxxxxxxx
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@xxxxxxxxxxxxxxxxxxxxxxx
_______________________________________________ docs mailing list -- docs@xxxxxxxxxxxxxxxxxxxxxxx To unsubscribe send an email to docs-leave@xxxxxxxxxxxxxxxxxxxxxxx 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@xxxxxxxxxxxxxxxxxxxxxxx
