[Qgis-community-team] New QGIS Documentation Subscriber

Sun Jun 5 19:09:20 PDT 2016

No worries Harrissou on the long email reply.  Sometimes it is helpful to explain things a little, thanks.

In viewing everyone’s suggestions, using the fix me link transferring the PDF pages into GitHub eliminates knowing the syntax allowing me to make changes from the get-go.  However, I used Word to make changes to the testing document as it was easy to move things around, this may not be the case within GitHub.  I have placed a pdf copy in Dropbox  (sending another email to everyone with the link). I only edited the first few pages to give all an idea of the user guide design layout.  Not, sure how easy or time intensive design layout could be within GitHub?

In addition, when I make changes using the fix me link to transfer the pdf to GitHub and it’s in my repository, will the changes I make affect the original (Master) document User Guide 2.14. Or will it ONLY affect my clone repository in my account?  Will everyone be able to go to my repository and see the changes I made to the document?  Hence, the reason I did not make any changes yet to the Github QGIS User Guide 2.14 document.

Best Regards

Angie

________________________________
From: DelazJ <delazj at gmail.com>
Sent: Saturday, June 4, 2016 3:58:45 AM
To: qgis-community-team at lists.osgeo.org; Angie Garcia
Subject: Re: [Qgis-community-team] New QGIS Documentation Subscriber

Hi,.

2016-06-04 7:25 GMT+02:00 Angie Garcia <amg832 at outlook.com<mailto:amg832 at outlook.com>>:
To move forward with editing documentation, I have created a sample of how the User Guide 2.14 could be modified.  Keep in mind this is only one idea, all input is welcomed.

Looking forward to reading this doc. No worry we are open to changes as far as they improve the project are sustainable and worth the effort

All changes were indicated with red font, I made changes up to end of chapter 1.  Need to upload pdf to repository.  Can someone provide best way to do this?  I have created my GitHub account and fork (created copy of repository), installed the Git, but not created the local repository.

Actually, from my experience, having a local repository is not that mandatory (except to keep uptodate your _master_ branch). I only needed it because:
- I wanted a clean history: I couldn't do all my changes in one go so needed to use git commands to merge them in one change (commit)
- I had to manage conflicts between my proposal (pull request) and changes done to the repo by others meanwhile
- and to have branch(es) that follow official master branch, (purists could say this is mandatory - but you can workaround thanks to GitHub web interface)

I worked on document aesthetics, content, consistency and followed along using QGIS software.  However, if a re-design change is made to the document, it would be a good idea to update other manuals.

consistency, improvement, sustainability, new ideas are all welcome...

The idea will be to edit one section/chapter at a time then upload it to the repository.

I think a more sustainable process would be using github directly to perform your changes so let's do a step by step modification, now that you have a github account. Let's say you'll like to fix things in the "Getting Started" chapter (http://docs.qgis.org/testing/en/docs/user_manual/introduction/getting_started.html):

1. Click the "Fix Me" link at the bottom of the page
2. this would open https://github.com/qgis/QGIS-Documentation/edit/master/source/docs/user_manual/introduction/getting_started.rst. A message at the top of the page will tell you that you don't have write access to this repo and your changes will be applied in a branch of your forked repo.
  2b. If your master branch is even with qgis/master, you can replace the link above by yours https://github.com/amg832/QGIS-Documentation/edit/master/source/docs/user_manual/introduction/getting_started.rst
3. following guidelines available at http://docs.qgis.org/testing/en/docs/documentation_guidelines/, do your changes
4. When you finish, at the bottom of the page, comment a bit what your changes are about and click on "Propose File change". This will generate a new branch (patch-xxx - i can't recall if you can name the branch) in your repo
  4b. If you use your own master branch (as said in 2b), you're strongly advised to commit in a new branch with a remindable name (let's use getStart). Avoid committing your changes in the master branch. Actually, it's good to have a branch even with the main project and master is usually used for that. Keep it just to merge qgis/master changes inside, not yours.
Now you have a file in https://github.com/amg832/QGIS-Documentation/patch-1/source/docs/user_manual/introduction/getting_started.rst (or https://github.com/amg832/QGIS-Documentation/getStart/source/docs/user_manual/introduction/getting_started.rst if 2b) different from the official doc with your changes. Now you need to inform about your changes and ask for merging (pull request to the main repo).
5. You get a "Comparing changes" page. Ensure that the base fork is qgis/QGIS-Documentation and its branch master
6. Click on "Create pull request", fill some info if needed and apply
7. A new PR is added to https://github.com/qgis/QGIS-Documentation/pulls and every body can look or comment it (under files tab).
8. And a repo maintainer can merge your work directly with the official doc if all is ok in one-click.
9. Until your PR is merged with the repo, you can add modifications to your proposal. Actually any new changes done to your branch patch-xxx (or getStart) is appended to your PR. Do it if the change has to do with your initial pull request, otherwise create a new branch with those changes following steps above.

Sorry for my long message if you already knew all this. There are other ways to do it but this one looked straight for me when I began contributing. Hope that it's useful to someone.

Regards,
Harrissou

2016-06-04 10:03 GMT+02:00 Alexandre Neto <senhor.neto at gmail.com<mailto:senhor.neto at gmail.com>>:

If you wanna share a PDF you could put it in Dropbox or something similar. The repository is not the place for it.

A sáb, 4/06/2016, 06:30, Angie Garcia <amg832 at outlook.com<mailto:amg832 at outlook.com>> escreveu:
To move forward with editing documentation, I have created a sample of how the User Guide 2.14 could be modified.  Keep in mind this is only one idea, all input is welcomed.

All changes were indicated with red font, I made changes up to end of chapter 1.  Need to upload pdf to repository.  Can someone provide best way to do this?  I have created my GitHub account and fork (created copy of repository), installed the Git, but not created the local repository.

I worked on document aesthetics, content, consistency and followed along using QGIS software.  However, if a re-design change is made to the document, it would be a good idea to update other manuals.

The idea will be to edit one section/chapter at a time then upload it to the repository.

Best Regards,
Angie

________________________________________
From: Qgis-community-team <qgis-community-team-bounces at lists.osgeo.org<mailto:qgis-community-team-bounces at lists.osgeo.org>> on behalf of Yves Jacolin <yjacolin at free.fr<mailto:yjacolin at free.fr>>
Sent: Thursday, June 2, 2016 5:17:40 AM
To: qgis-community-team at lists.osgeo.org<mailto:qgis-community-team at lists.osgeo.org>
Subject: Re: [Qgis-community-team] New QGIS Documentation Subscriber

Hello,

A good start for an english native speaker could be:
* make review of Pull request
* proof read the doc to see english error, etc. and create issue with the
correct sentence.

That would be a really huge enhancement, but also a hard work.

Y.

On Thursday, June 02, 2016 1:20:25 DelazJ wrote:
> Hi,
>
> Welcome Angie and thanks for offering your help!
>
> As already pointed out by Richard you'll find few recommendations to follow
> when contributing to QGIS Documentation writing at
> http://docs.qgis.org/testing/en/docs/documentation_guidelines/
> But prior to this, In order to contribute, you'll need as stated at
> http://qgis.org/en/site/getinvolved/document.html#becoming-a-documenter  to:
> - create a GitHub account
> - and fork (copy) the doc repo
>
> Once done, feel free to pick any issue in the list and write about. You can
> also go through the doc being written (docs.qgis.org/testing/en/docs<http://docs.qgis.org/testing/en/docs>) and
> fix potential typo errors, "bad english" (most of us are not native
> speaker) or review/comment contributions of others (
> https://github.com/qgis/QGIS-Documentation/pulls).
>
> Once again, welcome to you and if something is unclear, just ask. Someone
> will try to explain to you.
>
> Regards,
> Harrissou
>
> 2016-06-02 0:17 GMT+02:00 Alexandre Neto <senhor.neto at gmail.com<mailto:senhor.neto at gmail.com>>:
> > Angie,
> >
> > Welcome to the team. Thanks you for helping us with the docs.
> >
> > I normally do the screenshots, so anything you need, let me know. Are you
> > on github already?
> >
> > Alexandre Beto
> >
> > A qua, 1/06/2016, 22:50, Angie Garcia <amg832 at outlook.com<mailto:amg832 at outlook.com>> escreveu:
> >> Richard,
> >>
> >> English is my primary language.  Read QGIS is natively developed in
> >> English, if you need assistance in looking at text before pulling it into
> >> the docs, glad to help just need to know what needs to be done.
> >>
> >> Best Regards,
> >> Angie
> >>
> >>
> >> ________________________________________
> >> From: Richard Duivenvoorde <rdmailings at duif.net<mailto:rdmailings at duif.net>>
> >> Sent: Tuesday, May 31, 2016 11:53:43 PM
> >> To: Angie Garcia
> >> Cc: dassau at gbd-consult.de<mailto:dassau at gbd-consult.de>; Junior Delaz; Yves Jacolin; qgis-community
> >> Subject: Re: New QGIS Documentation Subscriber
> >>
> >> On 31-05-16 22:33, Angie Garcia wrote:
> >> > Hi Richard,
> >> >
> >> > I have recently subscribed and would like to participate with updating
> >> > User Guide and assist in suggestions to aid in the documentation work
> >> > flow.  In going through all online/materials, it mentioned that one
> >> > should contact team lead in specific area of interest to get some
> >> > assistance in the process.  I have cc Otto as he was the person I sent
> >> > email to, however, have not heard from him and thought you might be
> >> > able
> >> > to help me or point me in the right direction to move forward.
> >> >
> >> > Is there a new welcoming documentation packet which helps one get
> >> > setup,
> >> > have a mailing list of individuals to contact, talks a little about the
> >> > various emails and limitations, etc...
> >>
> >> Hi Angie,
> >>
> >> For what I know this:
> >>
> >> http://docs.qgis.org/testing/en/docs/documentation_guidelines/
> >>
> >> are the guidelines. In the README at:
> >>
> >> https://github.com/qgis/QGIS-Documentation
> >>
> >> is more information about how to actually BUILD the docs.
> >>
> >> Note that it is actually not persee nessecary to build it yourself. If
> >> you follow the 'fix me' link in the footer of the pages on current
> >> 'testing' (==2.14 to be) version:
> >>
> >> http://docs.qgis.org/testing/en/docs/user_manual/index.html
> >>
> >> you can write/fix smaller parts of the docs in Github.
> >>
> >> I added Harrisou and Yves in cc, they have been mostly active I think
> >> recently, and maybe can give you a hand too.
> >> I will also sent this email to the community list where most document
> >> writers hang out.
> >>
> >> Here:
> >>
> >> https://github.com/qgis/QGIS-Documentation/issues
> >> all issues labeld QGIS 2.14
> >> https://github.com/qgis/QGIS-Documentation/milestones/QGIS%202.14
> >> should be taken up in short notice.
> >> Not sure if you are native speaker, but we also look for native speakers
> >> to have a look at texts of others before pulling into the docs.
> >>
> >> Pick an issue, try something, ask... just DO it ;-)
> >>
> >> Regards,
> >>
> >> Richard Duivenvoorde
> >>
> >> ps reaching me in private is best done via richard at qgis.org... Using the
> >> rdmailings you end up in the big pile of mailinglists I have :-)
> >> BUT I prefer communicating through mailing lists as more people learn
> >> from this.
> >>
> >> _______________________________________________
> >> Qgis-community-team mailing list for organizing community resources such
> >> as documentation, translation etc..
> >> Qgis-community-team at lists.osgeo.org<mailto:Qgis-community-team at lists.osgeo.org>
> >> http://lists.osgeo.org/mailman/listinfo/qgis-community-team
> >
> > --
> > Alexandre Neto
> > ---------------------
> > @AlexNetoGeo
> > http://sigsemgrilhetas.wordpress.com
> > http://gisunchained.wordpress.com
> >
> > _______________________________________________
> > Qgis-community-team mailing list for organizing community resources such
> > as documentation, translation etc..
> > Qgis-community-team at lists.osgeo.org<mailto:Qgis-community-team at lists.osgeo.org>
> > http://lists.osgeo.org/mailman/listinfo/qgis-community-team

_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
Qgis-community-team at lists.osgeo.org<mailto:Qgis-community-team at lists.osgeo.org>
http://lists.osgeo.org/mailman/listinfo/qgis-community-team
_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
Qgis-community-team at lists.osgeo.org<mailto:Qgis-community-team at lists.osgeo.org>
http://lists.osgeo.org/mailman/listinfo/qgis-community-team
--
Alexandre Neto
---------------------
@AlexNetoGeo
http://sigsemgrilhetas.wordpress.com
http://gisunchained.wordpress.com

_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
Qgis-community-team at lists.osgeo.org<mailto:Qgis-community-team at lists.osgeo.org>
http://lists.osgeo.org/mailman/listinfo/qgis-community-team

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/qgis-community-team/attachments/20160606/a4152c3e/attachment-0001.html>