You are viewing a plain text version of this content. The canonical link for it is here.
Posted to github@arrow.apache.org by GitBox <gi...@apache.org> on 2021/12/01 14:23:25 UTC
[GitHub] [arrow] pitrou commented on a change in pull request #11823: ARROW-14761: [Doc] Helping with documentation
pitrou commented on a change in pull request #11823:
URL: https://github.com/apache/arrow/pull/11823#discussion_r760227845
##########
File path: docs/source/developers/guide/documentation.rst
##########
@@ -27,4 +27,65 @@
**************************
Helping with documentation
-**************************
\ No newline at end of file
+**************************
+
+
+A great way to contribute to the project is to improve
+documentation.
+
+If you are an Arrow user and you found some docs to be
+incomplete or inaccurate, share your hard-earned knowledge
+with the rest of the community.
+
+If you haven't come across an error in the documentation
+it is hard to find one and going through the docs in search
+for corrections is not a good way to go. In this case you can
+search for an issue that is dealing with the documentation
+on JIRA.
+
+.. note::
+ When searching for JIRA issue that deals with documentation
+ try selecting **Components** from **More** tab in JIRA search
+ and there find **Documentation** from the list.
+
+ See `Example search. <https://issues.apache.org/jira/browse/ARROW-14280?jql=project%20%3D%20ARROW%20AND%20status%20%3D%20Open%20AND%20resolution%20%3D%20Unresolved%20AND%20component%20%3D%20Documentation%20AND%20assignee%20in%20(EMPTY)%20ORDER%20BY%20priority%20DESC%2C%20updated%20DESC>`_
Review comment:
This URL points to a specific issue, we should give the link to the search summary instead, e.g. https://issues.apache.org/jira/issues/?jql=project%20%3D%20ARROW%20AND%20status%20%3D%20Open%20AND%20resolution%20%3D%20Unresolved%20AND%20component%20%3D%20Documentation%20AND%20assignee%20in%20(EMPTY)%20ORDER%20BY%20priority%20DESC%2C%20updated%20DESC
##########
File path: docs/source/developers/guide/documentation.rst
##########
@@ -27,4 +27,65 @@
**************************
Helping with documentation
-**************************
\ No newline at end of file
+**************************
+
+
+A great way to contribute to the project is to improve
+documentation.
+
+If you are an Arrow user and you found some docs to be
+incomplete or inaccurate, share your hard-earned knowledge
+with the rest of the community.
+
+If you haven't come across an error in the documentation
+it is hard to find one and going through the docs in search
+for corrections is not a good way to go. In this case you can
+search for an issue that is dealing with the documentation
+on JIRA.
+
+.. note::
+ When searching for JIRA issue that deals with documentation
+ try selecting **Components** from **More** tab in JIRA search
+ and there find **Documentation** from the list.
+
+ See `Example search. <https://issues.apache.org/jira/browse/ARROW-14280?jql=project%20%3D%20ARROW%20AND%20status%20%3D%20Open%20AND%20resolution%20%3D%20Unresolved%20AND%20component%20%3D%20Documentation%20AND%20assignee%20in%20(EMPTY)%20ORDER%20BY%20priority%20DESC%2C%20updated%20DESC>`_
+
+.. figure:: jira_doc_1.jpeg
Review comment:
Should these figures perhaps be indented so as to be displayed inside the note?
##########
File path: docs/source/developers/guide/documentation.rst
##########
@@ -27,4 +27,65 @@
**************************
Helping with documentation
-**************************
\ No newline at end of file
+**************************
+
+
+A great way to contribute to the project is to improve
+documentation.
+
+If you are an Arrow user and you found some docs to be
+incomplete or inaccurate, share your hard-earned knowledge
+with the rest of the community.
+
+If you haven't come across an error in the documentation
+it is hard to find one and going through the docs in search
+for corrections is not a good way to go. In this case you can
+search for an issue that is dealing with the documentation
+on JIRA.
+
+.. note::
+ When searching for JIRA issue that deals with documentation
+ try selecting **Components** from **More** tab in JIRA search
+ and there find **Documentation** from the list.
+
+ See `Example search. <https://issues.apache.org/jira/browse/ARROW-14280?jql=project%20%3D%20ARROW%20AND%20status%20%3D%20Open%20AND%20resolution%20%3D%20Unresolved%20AND%20component%20%3D%20Documentation%20AND%20assignee%20in%20(EMPTY)%20ORDER%20BY%20priority%20DESC%2C%20updated%20DESC>`_
+
+.. figure:: jira_doc_1.jpeg
+ :scale: 40 %
+ :alt: selecting Components in JIRA search
+
+ First select Components tab in JIRA.
+
+.. figure:: jira_doc_2.jpeg
+ :scale: 40 %
+ :alt: selecting Documentation in JIRA search
+
+ Then choose Documentation from the Components list.
+
+Documentation improvements are also a great way to gain some
+experience with our submission and review process without
+requiring a lot of local development environment setup.
+
+.. note::
+ Many documentation-only changes can be made directly in the
+ GitHub web interface by clicking the **edit** icon. This
+ will handle making a fork and a pull request for you.
+
+.. figure:: github_edit_1.jpeg
Review comment:
Same suggestion here (put those inside the note).
##########
File path: docs/source/developers/guide/documentation.rst
##########
@@ -27,4 +27,65 @@
**************************
Helping with documentation
-**************************
\ No newline at end of file
+**************************
+
+
+A great way to contribute to the project is to improve
+documentation.
+
+If you are an Arrow user and you found some docs to be
+incomplete or inaccurate, share your hard-earned knowledge
+with the rest of the community.
+
+If you haven't come across an error in the documentation
+it is hard to find one and going through the docs in search
+for corrections is not a good way to go. In this case you can
+search for an issue that is dealing with the documentation
+on JIRA.
+
+.. note::
+ When searching for JIRA issue that deals with documentation
Review comment:
It seems your editor is configured to use tab characters for indentation, can you change it to only insert space characters?
(also, conventionally, the indentation size for `.rst` files is 3 spaces :-))
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org