Re: Can you help me out with integrating editing to the docs It will take you 8,77 minutes to follow.

[Adam Samalik]

Hi Leslie,

I really value your work and I'd really like to help you to integrate it.
But rather than doing the integration work myself (for which, to be fair, I
don't have many spare cycles), I'd like to teach you how to do it yourself.
The benefits would be:

* The integration of your work wouldn't generate additional work for other
people, other than the actual review + feedback
* You would be able to get feedback in the PR itself — there is a space for
discussion, as well as posting inline comments
* Many different people could help with commenting, reviewing, and even
merging the changes
* You would get credit as those changes would be clearly marked as yours

I'd rather spent an hour teaching you how to do future changes yourself,
rather than doing it myself for 8.77 minutes. Especially with the amount of
work you do, I wouldn't be able to keep up long-term. Also, there are many
other people out there that could help to review the changes.

I know, git might be a new tool for many writers, and learning it might
require some effort, but using it has many benefits for large communities
such as Fedora, where we need to scale our work between many people living
in different parts of the world and different timezones. If we want to work
in a large community, or want to build a large community, we need to have
workflows that scale. And git is one of the least horrible options there.

So, I'm happy to have a video call with you, even for an hour, going
through the integration of your changes, so you feel comfortable doing them
yourself next time. Would that work for you?

Please let me know.

regards,
Adam

On Mon, Aug 20, 2018 at 5:43 PM Leslie S Satenstein 
wrote:
> Hi Adam,
>
> *Your response will go a long way to understanding what I mean and do by
> "editing"*
>
> Can you help me out with integrating editing to the *.adocs?
>
> What I have attached is one fairly short libreoffice writer document  (1.5
> pages)  and the corresponding updated Desktop.adoc.
>
> Before I can generate a pull request, I made a correction and asked some
> questions inside the libreoffice writer file.  Those questions, if properly
> responded to, are to be the modifications to be made to the corresponding
> *.adoc file. A third x.sh file  just invokes vim against the location to
> where the  target adoc file resides.
>
> I am and attaching a zip file with the updated Desktop.adoc and the
> corresponding libreoffice  "Desktop.adoc.odt".  The way I see things
> working, the libreoffice document is the working document. When it is
> clean, the contents therein are what is transfered to the corresponding
> *.adoc file and a PR sent.
> Can you please note. Not all document writers are git users.  They are
>
> writers, and can follow instructions. Please add a definition of a Pull
> Request.
>
> Pull Request:  A formal request document, transmitted to the owner of the
> git repository. The PR contains revisions or insertions that you are
> requesting for that git repository.
>
> Regards
> Leslie*
>
> *Leslie Satenstein*
> *Montréal Québec, Canada*

Can you help me out with integrating editing to the docs It will take you 8,77 minutes to follow.

[Richard England]

Would it be possible to create a video of or for this lesson so it can 
be shared later?

I, too, am finding the editing process difficult to get into.

On 08/22/2018 04:48 AM, Adam Samalik wrote:
> Hi Leslie,
>
> I really value your work and I'd really like to help you to integrate 
> it. But rather than doing the integration work myself (for which, to 
> be fair, I don't have many spare cycles), I'd like to teach you how to 
> do it yourself. The benefits would be:
> The integration of your work wouldn't generate additional work for
>
> other people, other than the actual review + feedback
> You would be able to get feedback in the PR itself — there is a
>
> space for discussion, as well as posting inline comments
> Many different people could help with commenting, reviewing, and
>
> even merging the changes
> You would get credit as those changes would be clearly marked as yours
>
> I'd rather spent an hour teaching you how to do future changes 
> yourself, rather than doing it myself for 8.77 minutes. Especially 
> with the amount of work you do, I wouldn't be able to keep up 
> long-term. Also, there are many other people out there that could help 
> to review the changes.
>
> I know, git might be a new tool for many writers, and learning it 
> might require some effort, but using it has many benefits for large 
> communities such as Fedora, where we need to scale our work between 
> many people living in different parts of the world and different 
> timezones. If we want to work in a large community, or want to build a 
> large community, we need to have workflows that scale. And git is one 
> of the least horrible options there.
>
> So, I'm happy to have a video call with you, even for an hour, going 
> through the integration of your changes, so you feel comfortable doing 
> them yourself next time. Would that work for you?
>
> Please let me know.
>
> regards,
> Adam
>
> On Mon, Aug 20, 2018 at 5:43 PM Leslie S Satenstein 
> <[e-mail] > wrote:
> Hi Adam,
> *
> *
> *Your response will go a long way to understanding what I mean and
> do by "editing"*
>
> Can you help me out with integrating editing to the *.adocs?
>
> What I have attached is one fairly short libreoffice writer
> document  (1.5 pages)  and the corresponding updated Desktop.adoc.
>
> Before I can generate a pull request, I made a correction and
> asked some questions inside the libreoffice writer file.  Those
> questions, if properly responded to, are to be the modifications
> to be made to the corresponding *.adoc file. A third x.sh file 
> just invokes vim against the location to where the  target adoc
> file resides.
>
> I am and attaching a zip file with the updated Desktop.adoc and
> the corresponding libreoffice "Desktop.adoc.odt".  The way I see
> things working, the libreoffice document is the working document.
> When it is clean, the contents therein are what is transfered to
> the corresponding *.adoc file and a PR sent.
>
>
> 2) Can you please note. Not all document writers are git users. 
> They are writers, and can follow instructions. Please add a
> definition of a Pull Request.
>
> Pull Request:  A formal request document, transmitted to the owner
> of the git repository. The PR contains revisions or insertions
> that you are requesting for that git repository.
>
>
> Regards
> *
>  Leslie
> *
> *Leslie Satenstein*
> *Montréal Québec, Canada*
>
> **
>
>
>
> --
> Adam Šamalík
>
> Software Engineer
> Red Hat
>
> docs mailing list -- [e-mail]
> To unsubscribe send an email to [e-mail]
> 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/[e-mail]/m...

Can you help me out with integrating editing to the docs It will take you 8,77 minutes to follow.

[Adam Samalik]

I've done a Fedora Classroom recently, covering the basics, incuding git
and a complete workflow. Recording:
https://m.youtube.com/watch?v=LkH2ugg49Ag

Happy to do even a more detailed one, including installation and setting up
git, generating a key and adding it to Pagure, and whatever else is needed.
Would that be helpful?

On Wed, 22 Aug 2018 at 18:58, Richard England  wrote:
> Would it be possible to create a video of or for this lesson so it can be
> shared later?
>
> I, too, am finding the editing process difficult to get into.
>
> On 08/22/2018 04:48 AM, Adam Samalik wrote:
>
> Hi Leslie,
>
> I really value your work and I'd really like to help you to integrate it.
> But rather than doing the integration work myself (for which, to be fair, I
> don't have many spare cycles), I'd like to teach you how to do it yourself.
> The benefits would be:
> The integration of your work wouldn't generate additional work for other
>
> people, other than the actual review + feedback
> You would be able to get feedback in the PR itself — there is a space
>
> for discussion, as well as posting inline comments
> Many different people could help with commenting, reviewing, and even
>
> merging the changes
> You would get credit as those changes would be clearly marked as yours
>
> I'd rather spent an hour teaching you how to do future changes yourself,
> rather than doing it myself for 8.77 minutes. Especially with the amount of
> work you do, I wouldn't be able to keep up long-term. Also, there are many
> other people out there that could help to review the changes.
>
> I know, git might be a new tool for many writers, and learning it might
> require some effort, but using it has many benefits for large communities
> such as Fedora, where we need to scale our work between many people living
> in different parts of the world and different timezones. If we want to work
> in a large community, or want to build a large community, we need to have
> workflows that scale. And git is one of the least horrible options there.
>
> So, I'm happy to have a video call with you, even for an hour, going
> through the integration of your changes, so you feel comfortable doing them
> yourself next time. Would that work for you?
>
> Please let me know.
>
> regards,
> Adam
>
> On Mon, Aug 20, 2018 at 5:43 PM Leslie S Satenstein 
> wrote:
> > Hi Adam,
> >
> > *Your response will go a long way to understanding what I mean and do by
> > "editing"*
> >
> > Can you help me out with integrating editing to the *.adocs?
> >
> > What I have attached is one fairly short libreoffice writer document
> > (1.5 pages)  and the corresponding updated Desktop.adoc.
> >
> > Before I can generate a pull request, I made a correction and asked some
> > questions inside the libreoffice writer file.  Those questions, if properly
> > responded to, are to be the modifications to be made to the corresponding
> > *.adoc file. A third x.sh file  just invokes vim against the location to
> > where the  target adoc file resides.
> >
> > I am and attaching a zip file with the updated Desktop.adoc and the
> > corresponding libreoffice  "Desktop.adoc.odt".  The way I see things
> > working, the libreoffice document is the working document. When it is
> > clean, the contents therein are what is transfered to the corresponding
> > *.adoc file and a PR sent.
> > Can you please note. Not all document writers are git users.  They are
> >
> > writers, and can follow instructions. Please add a definition of a Pull
> > Request.
> >
> > Pull Request:  A formal request document, transmitted to the owner of the
> > git repository. The PR contains revisions or insertions that you are
> > requesting for that git repository.
> >
> > Regards
> > Leslie *
> >
> > *Leslie Satenstein*
> > *Montréal Québec, Canada*
>
> --
> Adam Šamalík
>
> Software Engineer
> Red Hat
>
> docs mailing list -- [e-mail]
> To unsubscribe send an email to [e-mail]
> 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/[e-mail]/m...
>
> --

Adam Šamalík
---------------------------
Software Engineer
Red Hat

Can you help me out with integrating editing to the docs It will take you 8,77 minutes to follow.

[Leslie S Satenstein]

Please distinguish editing from writing.  This is what I do for the editing.Insure asciidoctor is installed, as well as libreoffice and gitgit clone a repository.enable git and create a branch of said repository  I will use as an example, the release notesFor each directory within the release notes repository, create a   libreoffice document directoryfor each *.adoc in each directory, run the followingcat  ~/bin/adoc
#!/bin/bash
if [ $# = 0 ];
then
   echo "command is  $0 asciidoc.adoc "
   echo "output to /tmp/asciidoc.html "
   echo "Also creates a /tmp/x.sh pointing vim to the asciidoc.adoc"
   exit 0
fi
bn=$(basename $1 .adoc)
dn=$(pwd)
inadoc=${bn}.adoc
asciidoctor --out-file /tmp/${inadoc}.html.odt ${bn}.adoc  2>/tmp/${inadoc}.errs
echo "vim ${dn}/$inadoc " >/tmp/x.sh
chmod 755 /tmp/x.sh
libreoffice --writer /tmp/${inadoc}.html.odt
#firefox /tmp/${bn}.html  
clear
ls -l  
#

for each *.adoc 
the script will create a libreoffice file.Use landscape setting. Format->Page set radio button landscape.
  Enable markup management via EDIT-->Track Changes and click Record,Show,Manage
Edit that file to identify changes or corrections.Once satisfied, save.If there is no one to review your edits, (I am proposing to do the review), pass the *.odt documentto a coordinator,  He will reject each inappropriate individual change using the LOwriter options.The changes that remain (and the coordinator can add or modify them) get back to the author.The author now edits the correspondint adoc file, matches the changes in the Writer document tothe adoc file, and updates the adoc file.He then submits the *.adoc file as a PR.
The following is an example of what a coordinator (repository owner) would look at for approval. If there are update refusals, the document goes back to the writer.  The author can also concurrently provide the *.adoc to the editor. The two are returned to the author for him/her to issue the Pull request. The editor would also update the accompanying adoc file.Here is an example of an edit of "Desktop.adoc".

And this is the corrected string after update to the *.adoc file.

Prior to this update, the [package]*fontconfig* cache files were placed in the `/var/cache/fontconfig` directory. This location is not compatible with the `OStree` model used by Fedora Atomic, which prevented using the same package for Atomic and other Fedora variants. To fix this incompatibility, the cache files have been moved to `/usr/lib/fontconfig/cache`.

If you want help with editing, and it is OK with Adam, Richard or others  I will be glad to devote time to reviewing your postings prior to your issuing a PR.  My location is in the CC above

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

On Wednesday, August 22, 2018, 12:58:00 p.m. EDT, Richard England  wrote:

Would it be possible to create a video of or for this lesson so it can be shared later?

I, too, am finding the editing process difficult to get into.

On 08/22/2018 04:48 AM, Adam Samalik wrote:

Hi Leslie, 
  I really value your work and I'd really like to help you to integrate it. But rather than doing the integration work myself (for which, to be fair, I don't have many spare cycles), I'd like to teach you how to do it yourself. The benefits would be: 
  * The integration of your work wouldn't generate additional work for other people, other than the actual review + feedback * You would be able to get feedback in the PR itself — there is a space for discussion, as well as posting inline comments * Many different people could help with commenting, reviewing, and even merging the changes * You would get credit as those changes would be clearly marked as yours 
  I'd rather spent an hour teaching you how to do future changes yourself, rather than doing it myself for 8.77 minutes. Especially with the amount of work you do, I wouldn't be able to keep up long-term. Also, there are many other people out there that could help to review the changes. 
  I know, git might be a new tool for many writers, and learning it might require some effort, but using it has many benefits for large communities such as Fedora, where we need to scale our work between many people living in different parts of the world and different timezones. If we want to work in a large community, or want to build a large community, we need to have workflows that scale. And git is one of the least horrible options there. 
  So, I'm happy to have a video call with you, even for an hour, going through the integration of your changes, so you feel comfortable doing them yourself next time. Would that work for you? 
  Please let me know. 
  regards, Adam  
  On Mon, Aug 20, 2018 at 5:43 PM Leslie S Satenstein  wrote:

Hi Adam, 
  Your response will go a long way to understanding what I mean and do by "editing"

Can you help me out with integrating editing to the *.adocs?

What I have attached is one fairly short libreoffice writer document  (1.5 pages)  and the corresponding updated Desktop.adoc.

Before I can generate a pull request, I made a correction and asked some questions inside the libreoffice writer file.  Those questions, if properly responded to, are to be the modifications to be made to the corresponding *.adoc file. A third  x.sh file  just invokes vim against the location to where the  target adoc file resides.

I am and attaching a zip file with the updated Desktop.adoc and the corresponding libreoffice  "Desktop.adoc.odt".  The way I see things working, the libreoffice document is the working document. When it is clean, the contents therein are what is  transfered to the corresponding *.adoc file and a PR sent.

2) Can you please note. Not all document writers are git users.  They are writers, and can follow instructions. Please add a definition of a Pull Request. 
  Pull Request:  A formal request document, transmitted to the owner of the git repository. The PR contains revisions or insertions that you are  requesting for that git repository.

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

--

Adam Šamalík
 ---------------------------
  Software Engineer
 Red Hat

_______________________________________________
docs mailing list -- [e-mail]
To unsubscribe send an email to [e-mail]
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/[e-mail]/m...

Can you help me out with integrating editing to the docs It will take you 8,77 minutes to follow.

[Adam Samalik]

Thanks for the explanation of your workflow! It's insightful and
interesting how we do many similar things, but in a different way.

Let me first walk you through the workflow we use, so we can see the
similarities, and then figure out the next steps for the long-term.

If I wanted to edit something in the Fedora Docs, let's say the Fedora 28
Release Notes, I would do:

1) Fork the source repository and make a local copy. How:
I would go to the source repository:
https://pagure.io/fedora-docs/release-notes/ (All source repositories are
listed here: https://pagure.io/fedora-docs/docs-fp-o)
I would click at "Fork" at the top-right corner which would create my own
copy of the repository on the server.
Then I would open my fork in the web browser
https://pagure.io/fork/asamalik/fedora-docs/release-notes and copied the
"SSH" URL under Source GIT URLs.
In my terminal, I would clone my fork by:
$ git clone ssh://[e-mail]/forks/asamalik/fedora-docs/release-notes.git
Since I want to do changes for Fedora 28, I need to switch to the f28
branch. (A list of all branches is on the web UI we've already seen, at the
right side. Branch names should be intuitive, so after seeing "f27, f28,
master, etc.", I've guessed that f28 is the right one.)
$ git checkout f28

2) Do the edits in the local copy of the fork. How:
I would edit the .adoc files I want to edit. I would do multiple changes at
once, that's fine. However, I would try to do changes of one "type" for a
lack of a better term. For example, grammar edits. A complete rewrite of
one page or a few related pages. Or adding some missing content. etc.
To preview my changes, I could use the instructions at the README.md which
says I should run "./build.sh && ./preview.sh".

3) Commit and push the changes to the fork on the server. How:
After I'm done with the changes I would commit them (register the changes
with the local copy of the fork):
$ git add .
$ git commit -m "describing my change here in about 8 words"
And then pushing the commits (applying the local changes to the fork on the
server, so anyone can see it)

4) Send a PR. How:
Now I want to apply the changes I have in my fork on the server to the
original repository. This is done by submitting a PR (pull-request, a
request to the owner of the original repository to accept the changes I
have made).
For that, I would open the original repository:
https://pagure.io/fedora-docs/release-notes , click on the "Pull Requests"
tab, then on the blue "File Pull Request" drop-down, and select my fork and
the branch I have edited. In this case that would be
"[asamalik/release-notes] [f28]".
Now that I've selected the PR goes from asamalik/release-notes f28, I need
to make sure it goes to the right branch in the target repository. I need
to select "f28" in the dropdown that now probably says "master".
Now, I need to add a title and a description of what and why I've done.
I can also review the changes by clicking at "Files Changed" at the very
bottom.
Finally, click "Create" and the PR has been submitted.

5) Someone needs to do a review. How:
Someone will check the changes and provides feedback. I can use the
built-in discussion to discuss the changes with the reviewer. The reviewer
either merges the PR, or asks for additional changes.
Good thing here is that I don't have to make my changes perfect at the
first try. I can even ask for suggestions in the PR itself. And also,
multiple different people can provide feedback. That's how we can scale
across many people in the community.

6) Just sometimes, making additional changes. How:
I would go to the local copy of my fork, do the changes (step 2 above), and
commit and push the changes (step 3 above). They will be applied
automatically to the PR, because I have modified the same branch.

So, that's it.

Leslie, I have found three major differences between your workflow and the
one I've just described:

1) The way we do the preview. We have provided tooling to preview the whole
repository at once. That's useful for internal links, for example. Let me
know if I can help with getting that work.

2) One change at a time vs. multiple changes at once. We do multiple
changes at once, and provide feedback on all of them. It's always possible
to say something like "I like the first five changes you've made, but I
would do the last one differently". And then we can iterate. Which brings
me to the third point:

3) We iterate. We don't expect things to be perfect at the first try.
That's why we don't distinguish between a "review before submitting a PR"
and the PR itself. We just submit the PR, get a feedback there, and if
needed, we can do another set of changes based on the feedback.

This way, we don't need to send anything via email to individual people.
Anyone in the community can provide feedback to the changes. And multiple
people with the sufficient permissions can merge the changes.

What do you think? Does that make sense?

And as I said earlier, I'm happy to walk you through the whole process over
a video call + screen share. We just need to figure out the best time as
I'm in Europe, so it would probably be your morning and my evening.

Cheers!
Adam

On Thu, Aug 23, 2018 at 6:35 PM Leslie S Satenstein 
wrote:
> Please distinguish editing from writing.  This is what I do for the
> editing.
> Insure asciidoctor is installed, as well as libreoffice and git
> git clone a repository.
> enable git and create a branch of said repository  I will use as an
> example, the release notes
> For each directory within the release notes repository, create a
> libreoffice document directory
> for each *.adoc in each directory, run the following
> cat  ~/bin/adoc
>
> *#!/bin/bashif [ $# = 0 ];then   echo "command is  $0 asciidoc.adoc "
> echo "output to /tmp/asciidoc.html "   echo "Also creates a /tmp/x.sh
> pointing vim to the asciidoc.adoc"   exit 0fibn=$(basename $1
> .adoc)dn=$(pwd)inadoc=${bn}.adocasciidoctor --out-file
> /tmp/${inadoc}.html.odt ${bn}.adoc  2>/tmp/${inadoc}.errsecho "vim
> ${dn}/$inadoc " >/tmp/x.shchmod 755 /tmp/x.shlibreoffice --writer
> /tmp/${inadoc}.html.odt#firefox /tmp/${bn}.html  clearls -l  #*
>
> for each *.adoc
> the script will create a libreoffice file.
> Use landscape setting. Format->Page set radio button landscape.
>
> Enable markup management via EDIT-->Track Changes and click
> Record,Show,Manage
>
> Edit that file to identify changes or corrections.
> Once satisfied, save.
> If there is no one to review your edits, (I am proposing to do the
> review), pass the *.odt document
> to a coordinator,  He will reject each inappropriate individual change
> using the LOwriter options.
> The changes that remain (and the coordinator can add or modify them) get
> back to the author.
> The author now edits the correspondint adoc file, matches the changes in
> the Writer document to
> the adoc file, and updates the adoc file.
> He then submits the *.adoc file as a PR.
>
> The following is an example of what a coordinator (repository owner) would
> look at for approval. If there are update refusals, the document goes back
> to the writer.  The author can also concurrently provide the *.adoc to the
> editor. The two are returned to the author for him/her to issue the Pull
> request. The editor would also update the accompanying adoc file.
> Here is an example of an edit of "Desktop.adoc".
>
> [image: Inline image]
>
> And this is the corrected string after update to the *.adoc file.
>
> Prior to this update, the [package]*fontconfig* cache files were placed in
> the `/var/cache/fontconfig` directory. This location is not compatible with
> the `OStree` model used by Fedora Atomic, which prevented using the same
> package for Atomic and other Fedora variants. To fix this incompatibility,
> the cache files have been moved to `/usr/lib/fontconfig/cache`.
>
> If you want help with editing, and it is OK with Adam, Richard or others
> I will be glad to devote time to reviewing your postings prior to your
> issuing a PR.  My location is in the CC above
>
> Regards
> Leslie*
>
> *Leslie Satenstein*
> *Montréal Québec, Canada*
>
> On Wednesday, August 22, 2018, 12:58:00 p.m. EDT, Richard England <
> [e-mail]> wrote:
>
> Would it be possible to create a video of or for this lesson so it can be
> shared later?
>
> I, too, am finding the editing process difficult to get into.
>
> On 08/22/2018 04:48 AM, Adam Samalik wrote:
>
> Hi Leslie,
>
> I really value your work and I'd really like to help you to integrate it.
> But rather than doing the integration work myself (for which, to be fair, I
> don't have many spare cycles), I'd like to teach you how to do it yourself.
> The benefits would be:
> The integration of your work wouldn't generate additional work for other
>
> people, other than the actual review + feedback
> You would be able to get feedback in the PR itself — there is a space
>
> for discussion, as well as posting inline comments
> Many different people could help with commenting, reviewing, and even
>
> merging the changes
> You would get credit as those changes would be clearly marked as yours
>
> I'd rather spent an hour teaching you how to do future changes yourself,
> rather than doing it myself for 8.77 minutes. Especially with the amount of
> work you do, I wouldn't be able to keep up long-term. Also, there are many
> other people out there that could help to review the changes.
>
> I know, git might be a new tool for many writers, and learning it might
> require some effort, but using it has many benefits for large communities
> such as Fedora, where we need to scale our work between many people living
> in different parts of the world and different timezones. If we want to work
> in a large community, or want to build a large community, we need to have
> workflows that scale. And git is one of the least horrible options there.
>
> So, I'm happy to have a video call with you, even for an hour, going
> through the integration of your changes, so you feel comfortable doing them
> yourself next time. Would that work for you?
>
> Please let me know.
>
> regards,
> Adam
>
> On Mon, Aug 20, 2018 at 5:43 PM Leslie S Satenstein 
> wrote:
>
> Hi Adam,
>
> *Your response will go a long way to understanding what I mean and do by
> "editing"*
>
> Can you help me out with integrating editing to the *.adocs?
>
> What I have attached is one fairly short libreoffice writer document  (1.5
> pages)  and the corresponding updated Desktop.adoc.
>
> Before I can generate a pull request, I made a correction and asked some
> questions inside the libreoffice writer file.  Those questions, if properly
> responded to, are to be the modifications to be made to the corresponding
> *.adoc file. A third x.sh file  just invokes vim against the location to
> where the  target adoc file resides.
>
> I am and attaching a zip file with the updated Desktop.adoc and the
> corresponding libreoffice  "Desktop.adoc.odt".  The way I see things
> working, the libreoffice document is the working document. When it is
> clean, the contents therein are what is transfered to the corresponding
> *.adoc file and a PR sent.
> Can you please note. Not all document writers are git users.  They are
>
> writers, and can follow instructions. Please add a definition of a Pull
> Request.
>
> Pull Request:  A formal request document, transmitted to the owner of the
> git repository. The PR contains revisions or insertions that you are
> requesting for that git repository.
>
> Regards
> Leslie *
>
> *Leslie Satenstein*
> *Montréal Québec, Canada*
>
> --
> Adam Šamalík
>
> Software Engineer
> Red Hat
>
> docs mailing list -- [e-mail]
> To unsubscribe send an email to [e-mail]
> 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/[e-mail]/m...

Can you help me out with integrating editing to the docs It will take you 8,77 minutes to follow.

[Leslie S Satenstein]

I am responding inline and will later do some experimenting with your instructions.

Leslie
    On Friday, August 24, 2018, 7:00:09 a.m. EDT, Adam Samalik  wrote:  
 Adam Says===========
 Thanks for the explanation of your workflow! It's insightful and interesting how we do many similar things, but in a different way.Let me first walk you through the workflow we use, so we can see the similarities, and then figure out the next steps for the long-term.If I wanted to edit something in the Fedora Docs, let's say the Fedora 28 Release Notes, I would do:
1) Fork the source repository and make a local copy. How:I would go to the source repository: https://pagure.io/fedora-docs/release-notes/ (All source repositories are listed here: https://pagure.io/fedora-docs/docs-fp-o)I would click at "Fork" at the top-right corner which would create my own copy of the repository on the server. Then I would open my fork in the web browser https://pagure.io/fork/asamalik/fedora-docs/release-notes and copied the "SSH" URL under Source GIT URLs.In my terminal, I would clone my fork by:$ git clone ssh://[e-mail]/forks/asamalik/fedora-docs/release-notes.gitSince I want to do changes for Fedora 28, I need to switch to the f28 branch. (A list of all branches is on the web UI we've already seen, at the right side. Branch names should be intuitive, so after seeing "f27, f28, master, etc.", I've guessed that f28 is the right one.)$ git checkout f28
=====================================================================
Leslie says
=========
With Bex's notes, in April past, I had forked from the "Master", which was F28. These forks were the "document-guide", "install-guide", "system-administrators-guide" and I have completed the edits of the *.adoc files in each of the mentioned gits. (I sent you zip files of same). Since then I have completed the fourth git, the release-guide.  I have not put it into a zip file to you and Bex.

I used  zip file attachments, since RedHat rejects tar file attachments. I believe that emails with zip files attachments are not blocked and you should each have copies. I can resend them
----------------------------------------------------------------------------------------------------
Adam continues=============
2) Do the edits in the local copy of the fork. How:I would edit the .adoc files I want to edit. I would do multiple changes at once, that's fine. However, I would try to do changes of one "type" for a lack of a better term. For example, grammar edits. A complete rewrite of one page or a few related pages. Or adding some missing content. etc. To preview my changes, I could use the instructions at the README.md which says I should run "./build.sh && ./preview.sh".==============================================================================Leslie continues=============
ONE) I tried your way. my answer. There are not enough hours in the six months between releases to do the workflow as you suggest. I tried your way and came to the opinion that the poor quailty of the mentioned guides was because it was too much cycling back and forth,  iterating to process the adoc, checking the output and looping to reprocess; only working with the *.adoc and it's output.  Too many iterations and much effort  to check one's own work. Your way may work for very minimal rework. Even so, you have to loop back and forth to verify the adoc file after every few changes. When you do, each loop loses the previous edits -- no record of  changes.
 TWO). An editor person may revise the first, tenth words of a paragraph, or reorder a sentence to make it read better. He may touch other lines within the same adoc file. When I will send up the PR for that adoc, it is an "all or non acceptance or rejection".   
THREE) .Benefit of including the use of LO writer to edit (not excluding the adoc). 
a) LO writer comes with Fedorab) I use it in the ribbon mode (see immediate print-screen) as to what I am highlighting.

----------------------------------------------------------------------------------------->> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
c) The corresponding writer document shows inline, all before/after edits. 
Notice the convenience of having the record, review, management comment and reject icons within easy reach. 
I found it expedient to use asciidoctor to create the LibreOffice word document. I edit that word document equivalent, and at the end of the editing, I go to the top of the LO document and back-port the changes to the *.adoc .  For backporting, I have the terminal open with vi on the *.adoc and the open LO document. I do the matching and adjust the *.adoc, and save it and if necessary, do an second output to confirm I did not goof up.   
The benefits of doing the editing with LOwriter, are:

i) eye catchers, with revision bars at the left margin (spacing or commas or periods are hard to catch otherwise)
ii) you can see the before/after in the text, and even reject or update your own changes.
iii) I can add comments to explain why I did what I did or even ask questions. If I send you the LO document, you can accept or reject each markup, or add your own. 
iv)The LO writer document serves to as the update output for the related adoc. v) Its easier to read a lo writer file than a *.adoc file.vi) I can do an hour or two of editing, save the writer document, and return to it later. I know exactly where I left off.

---------------------------------------------------------------------------------------------------------------------------------
Adam continues==============
3) Commit and push the changes to the fork on the server. How:After I'm done with the changes I would commit them (register the changes with the local copy of the fork):$ git add .$ git commit -m "describing my change here in about 8 words"       Was done with my aforementioned gits housed within the zip files.
And then pushing the commits (applying the local changes to the fork on the server, so anyone can see it)

4) Send a PR. How:Now I want to apply the changes I have in my fork on the server to the original repository.  This is done by submitting a PR (pull-request, a request to the owner of the original repository to accept the changes I have made).=========================================================================
Leslie says========Not sure of this section that you wrote.  Do you mean "Now I want to transfer the changes I have in my "local fork" on onto the server and into the original repository."?  Is it the entire repository that I transfer and does the repository see my branch. To what state do I have to leave my repository before I do the PR (branch or master), or do I just send the delta files, one by one?
------------------------------------------------------------------------------------------------------------------------------------------Adam continued=============
For that, I would open the original repository: https://pagure.io/fedora-docs/release-notes , click on the "Pull Requests" tab, then on the blue "File Pull Request" drop-down, and select my fork and the branch I have edited. In this case that would be "[asamalik/release-notes] [f28]".Now that I've selected the PR goes from asamalik/release-notes f28, I need to make sure it goes to the right branch in the target repository. I need to select "f28" in the dropdown that now probably says "master".Now, I need to add a title and a description of what and why I've done.I can also review the changes by clicking at "Files Changed" at the very bottom.Finally, click "Create" and the PR has been submitted.
5) Someone needs to do a review. How:Someone will check the changes and provides feedback. I can use the built-in discussion to discuss the changes with the reviewer. The reviewer either merges the PR, or asks for additional changes.Good thing here is that I don't have to make my changes perfect at the first try. I can even ask for suggestions in the PR itself. And also, multiple different people can provide feedback. That's how we can scale across many people in the community.============================================================================Leslie saysI edited almost every *.adoc within the aforementioned git files.  Is he going to accept/reject adoc by adoc? How does this work. 
It took me in total, with 4 git repositories, and doing about 20 pages/hr, nearly 200hrs to do the editing and backporting.Do you have a test/play area that I can try the PR and we can see how it goes? 
---------------------------------------------------------------------------------------------------------------------------------------------Adam continued

6) Just sometimes, making additional changes. How:I would go to the local copy of my fork, do the changes (step 2 above), and commit and push the changes (step 3 above). They will be applied automatically to the PR, because I have modified the same branch.
So, that's it.

Leslie, I have found three major differences between your workflow and the one I've just described:
1) The way we do the preview. We have provided tooling to preview the whole repository at once. That's useful for internal links, for example. Let me know if I can help with getting that work.
2) One change at a time vs. multiple changes at once. We do multiple changes at once, and provide feedback on all of them. It's always possible to say something like "I like the first five changes you've made, but I would do the last one differently". And then we can iterate. Which brings me to the third point:
3) We iterate. We don't expect things to be perfect at the first try. That's why we don't distinguish between a "review before submitting a PR" and the PR itself. We just submit the PR, get a feedback there, and if needed, we can do another set of changes based on the feedback.

This way, we don't need to send anything via email to individual people. Anyone in the community can provide feedback to the changes. And multiple people with the sufficient permissions can merge the changes.
What do you think? Does that make sense?
And as I said earlier, I'm happy to walk you through the whole process over a video call + screen share. We just need to figure out the best time as I'm in Europe, so it would probably be your morning and my evening.
Cheers!Adam
==============================================================================Leslie saysSending up a repository at a time is just great. Is there a play area.  Do you have software to view my terminal and to watch what I am doing.  If not you, I have unlimited north america phone use, that includes Canada USA.  Are you in the USA?

End of discussion==============
On Thu, Aug 23, 2018 at 6:35 PM Leslie S Satenstein  wrote:

Please distinguish editing from writing.  This is what I do for the editing.Insure asciidoctor is installed, as well as libreoffice and gitgit clone a repository.enable git and create a branch of said repository  I will use as an example, the release notesFor each directory within the release notes repository, create a   libreoffice document directoryfor each *.adoc in each directory, run the followingcat  ~/bin/adoc
#!/bin/bash
if [ $# = 0 ];
then
   echo "command is  $0 asciidoc.adoc "
   echo "output to /tmp/asciidoc.html "
   echo "Also creates a /tmp/x.sh pointing vim to the asciidoc.adoc"
   exit 0
fi
bn=$(basename $1 .adoc)
dn=$(pwd)
inadoc=${bn}.adoc
asciidoctor --out-file /tmp/${inadoc}.html.odt ${bn}.adoc  2>/tmp/${inadoc}.errs
echo "vim ${dn}/$inadoc " >/tmp/x.sh
chmod 755 /tmp/x.sh
libreoffice --writer /tmp/${inadoc}.html.odt
#firefox /tmp/${bn}.html  
clear
ls -l  
#

for each *.adoc 
the script will create a libreoffice file.Use landscape setting. Format->Page set radio button landscape.
  Enable markup management via EDIT-->Track Changes and click Record,Show,Manage
Edit that file to identify changes or corrections.Once satisfied, save.If there is no one to review your edits, (I am proposing to do the review), pass the *.odt documentto a coordinator,  He will reject each inappropriate individual change using the LOwriter options.The changes that remain (and the coordinator can add or modify them) get back to the author.The author now edits the correspondint adoc file, matches the changes in the Writer document tothe adoc file, and updates the adoc file.He then submits the *.adoc file as a PR.
The following is an example of what a coordinator (repository owner) would look at for approval. If there are update refusals, the document goes back to the writer.  The author can also concurrently provide the *.adoc to the editor. The two are returned to the author for him/her to issue the Pull request. The editor would also update the accompanying adoc file.Here is an example of an edit of "Desktop.adoc".

And this is the corrected string after update to the *.adoc file.

Prior to this update, the [package]*fontconfig* cache files were placed in the `/var/cache/fontconfig` directory. This location is not compatible with the `OStree` model used by Fedora Atomic, which prevented using the same package for Atomic and other Fedora variants. To fix this incompatibility, the cache files have been moved to `/usr/lib/fontconfig/cache`.

If you want help with editing, and it is OK with Adam, Richard or others  I will be glad to devote time to reviewing your postings prior to your issuing a PR.  My location is in the CC above

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

On Wednesday, August 22, 2018, 12:58:00 p.m. EDT, Richard England  wrote:

Would it be possible to create a video of or for this lesson so it can be shared later?

I, too, am finding the editing process difficult to get into.

On 08/22/2018 04:48 AM, Adam Samalik wrote:

Hi Leslie, 
  I really value your work and I'd really like to help you to integrate it. But rather than doing the integration work myself (for which, to be fair, I don't have many spare cycles), I'd like to teach you how to do it yourself. The benefits would be: 
  * The integration of your work wouldn't generate additional work for other people, other than the actual review + feedback * You would be able to get feedback in the PR itself — there is a space for discussion, as well as posting inline comments * Many different people could help with commenting, reviewing, and even merging the changes * You would get credit as those changes would be clearly marked as yours 
  I'd rather spent an hour teaching you how to do future changes yourself, rather than doing it myself for 8.77 minutes. Especially with the amount of work you do, I wouldn't be able to keep up long-term. Also, there are many other people out there that could help to review the changes. 
  I know, git might be a new tool for many writers, and learning it might require some effort, but using it has many benefits for large communities such as Fedora, where we need to scale our work between many people living in different parts of the world and different timezones. If we want to work in a large community, or want to build a large community, we need to have workflows that scale. And git is one of the least horrible options there. 
  So, I'm happy to have a video call with you, even for an hour, going through the integration of your changes, so you feel comfortable doing them yourself next time. Would that work for you? 
  Please let me know. 
  regards, Adam  
  On Mon, Aug 20, 2018 at 5:43 PM Leslie S Satenstein  wrote:

Hi Adam, 
  Your response will go a long way to understanding what I mean and do by "editing"

Can you help me out with integrating editing to the *.adocs?

What I have attached is one fairly short libreoffice writer document  (1.5 pages)  and the corresponding updated Desktop.adoc.

Before I can generate a pull request, I made a correction and asked some questions inside the libreoffice writer file.  Those questions, if properly responded to, are to be the modifications to be made to the corresponding *.adoc file. A third  x.sh file  just invokes vim against the location to where the  target adoc file resides.

I am and attaching a zip file with the updated Desktop.adoc and the corresponding libreoffice  "Desktop.adoc.odt".  The way I see things working, the libreoffice document is the working document. When it is clean, the contents therein are what is  transfered to the corresponding *.adoc file and a PR sent.

2) Can you please note. Not all document writers are git users.  They are writers, and can follow instructions. Please add a definition of a Pull Request. 
  Pull Request:  A formal request document, transmitted to the owner of the git repository. The PR contains revisions or insertions that you are  requesting for that git repository.

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

--

Adam Šamalík
 ---------------------------
  Software Engineer
 Red Hat

_______________________________________________
docs mailing list -- [e-mail]
To unsubscribe send an email to [e-mail]
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/[e-mail]/m...