Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

doc: add steps for updating documentation to document contribution page #1733

Open
7 of 11 tasks
otegami opened this issue Mar 6, 2024 · 4 comments · May be fixed by #1786
Open
7 of 11 tasks

doc: add steps for updating documentation to document contribution page #1733

otegami opened this issue Mar 6, 2024 · 4 comments · May be fixed by #1786
Labels
Feature

Comments

@otegami
Copy link
Contributor

otegami commented Mar 6, 2024 •
edited
Loading

What is your problem?

As a new contributor, I find it challenging to understand the process for contributing updates to the Groonga documentation. It would be helpful for them to add following steps to introduction.rst.

  • Editing the documentation
  • Previewing changes
  • Submitting changes

My suggestions

I propose to add a new sections to the introduction.rst about the documentation update process.

  • Edit Documentation Sources
  • Reflect Your Modifications
  • Preview Your Modifications on HTML
  • Update Translations
  • Reflect Your Translations
  • Preview Your Translations on HTML
  • Send Pull Request to Groonga Repository
  • Add the link for Sending patch in Preview Your Modifications on HTML

Next Steps after this issue

The content will be similar a little bit to the I18N page, but with a new flow.
We'll think about combining them after updating this introduction.rst.

Outdated: First feature request

Split contribution/documentation/introduction.rst into Two Pages like introduction and editing_guide

What is your problem?

To improve the contribution guide, I propose restructuring the current contribution/documentation/introduction.rst by splitting it into two separate pages. This change focuses on the following parts.

  1. Guide the process of building the documentation for viewing purposes as a previous step for contribution
  2. Guide the process of editing and submitting changes via pull requests for contribution

Proposed Changes:

I want to write the content like the following each page.

  • Introduction.rst
    • Topic: Guide the process of building the documentation for viewing purposes as a previous step for contribution
    • Sections:
      • Introduction
      • How to fork and clone the Groonga repository
      • Install depended software
      • Run cmake with --preset=doc
      • Generate HTML
  • (New Page) editing_guide.rst
    • Topic: Guide the process of editing and submitting changes via pull requests for contribution
    • Sections:
      • How to edit document
      • Edit documentation sources
      • Reflect your modifications
      • Preview your modifications on HTML
      • Update translations
      • Reflect your translations
      • Preview your translations on HTML
      • Send pull request to Groonga Repository

Expected TODO List

  • Introduction.rst
    • Remove the Update section from introduction.rst
  • (New Page) editing_guide.rst
    • Add new editing_guide page under contribution/documentation/
    • Write the following section one by one
      • How to edit document
      • Edit documentation sources
      • Reflect your modifications
      • Preview your modifications on HTML
      • Update translations
      • Reflect your translations
      • Preview your translations on HTML
      • Send pull request to Groonga Repository

How to reproduce it

No response
@otegami otegami added the Feature label Mar 6, 2024
@abetomo
Copy link
Contributor

abetomo commented Mar 6, 2024

Is there a purpose of having the same structure as this document and splitting the common parts?
If so, why not start by making contribution/documentation/introduction.rst the same structure, instead of splitting it up first?
It seems to me that this would make it easier to check common parts.

@otegami
Copy link
Contributor Author

otegami commented Mar 6, 2024

@abetomo
Thanks. I agree with your opinion because in this moment we are not sure splitting this document is better way.
I will update the current document and then think of the next step. How do you think of the following idea? If you agree with me, I will change the title and content of this issue.

doc: add steps for updating documentation to document contribution page

What is your problem?

As a new contributor, I find it challenging to understand the process for contributing updates to the Groonga documentation. It would be helpful for them to add following steps to introduction.rst.

  • Editing the documentation
  • Previewing changes
  • Submitting changes

My suggestions

I propose to add a new sections to the introduction.rst about the documentation update process.

  • Edit Documentation Sources
  • Reflect Your Modifications
  • Preview Your Modifications on HTML
  • Update Translations
  • Reflect Your Translations
  • Preview Your Translations on HTML
  • Send Pull Request to Groonga Repository

Next Steps after this issue

The content will be similar a little bit to the I18N page, but with a new flow.
We'll think about combining them after updating this introduction.rst.

@abetomo
Copy link
Contributor

abetomo commented Mar 6, 2024

I think that is a good way to proceed.

@otegami otegami changed the title Split contribution/documentation/introduction.rst into Two Pages like introduction and editing_guide doc: add steps for updating documentation to document contribution page Mar 6, 2024
@otegami
Copy link
Contributor Author

otegami commented Mar 6, 2024

Thanks! I've just updated the issue.

This was referenced Mar 6, 2024
Closed
Merged
kou added a commit that referenced this issue Mar 22, 2024
@otegami @kou
Add How to edit documentation to contribution documentation guide (#…
e0a493e 
…1734)

Related Issue: #1733

I will add a new sections to the `introduction.rst` about the
documentation update process.
- [x] Edit Documentation Sources <- This PR is right here!

I will do the below tasks at the following PRs.
- [ ] Reflect Your Modifications
- [ ] Preview Your Modifications on HTML
- [ ] Update Translations
- [ ] Reflect Your Translations
- [ ] Preview Your Translations on HTML
- [ ] Send Pull Request to Groonga Repository

---------

Co-authored-by: Sutou Kouhei <kou@cozmixng.org>
@otegami otegami mentioned this issue Mar 26, 2024
Merged
5 tasks
kou pushed a commit that referenced this issue Mar 27, 2024
@otegami
doc contribution/documentation: previews modifications on HTML (#1745)
bb7d0f1 
Related Issue: #1733

I will add a new sections to the `introduction.md` about the
documentation update process.
- [x] Preview Your Modifications on HTML files

I will do the below tasks at the following PRs.
- [ ] Update Translations
- [ ] Reflect Your Translations
- [ ] Preview Your Translations on HTML
- [ ] Send Pull Request to Groonga Repository
@otegami otegami mentioned this issue Mar 27, 2024
Merged
4 tasks
kou pushed a commit that referenced this issue Mar 29, 2024
@otegami
doc contribution/documentation: translate documentation (#1746)
6a70062 
Related Issue: #1733

I will add a new sections to the `introduction.md` about translating
documentation.
- [x] Update Translations <- This PR is here.

I will do the below tasks at the following PRs.
- [ ] Reflect Your Translations
- [ ] Preview Your Translations on HTML
- [ ] Send Pull Request to Groonga Repository
@otegami otegami mentioned this issue Apr 1, 2024
Merged
4 tasks
kou pushed a commit that referenced this issue Apr 2, 2024
@otegami
doc contribution/documentation: add how to reflect translations to `.…
adc3926 
…po` files to the translate doc section (#1750)

Related Issue: #1733

I will add a new sections to the `introduction.md` about translating
documentation.
- [x] Reflect Your Translations without Japanese translations
- [x] Add Japanese translations to Reflect Your Translations

I will do the below tasks at the following PRs.
- [ ] Preview Your Translations on HTML
- [ ] Send Pull Request to Groonga Repository
@otegami otegami mentioned this issue Apr 2, 2024
Merged
3 tasks
komainu8 pushed a commit that referenced this issue Apr 3, 2024
@otegami
doc contribution/documentation: add how to preview translations on HT…
95f8705 
…ML files to the translate doc section (#1751)

Related Issue: #1733

I will add a new sections to the `introduction.md` about translating
documentation.
- [x] Preview Your Translations on HTML without Japanese translations

I will do the below tasks at the following PRs.
- [ ] Add Japanese translations to Preview Your Translations on HTML
- [ ] Send Pull Request to Groonga Repository
@otegami otegami mentioned this issue Apr 3, 2024
Merged
2 tasks
komainu8 pushed a commit that referenced this issue Apr 4, 2024
@otegami
doc contribution/documentation: translate `Preview translations on HT…
f0d5a34 
…ML files` in Japanese (#1752)

Related Issue: #1733

- [x] Add Japanese translations to Preview Your Translations on HTML

I will do the below tasks at the following PRs.

- [ ] Send Pull Request to Groonga Repository
@otegami otegami mentioned this issue Apr 4, 2024
Merged
2 tasks
komainu8 pushed a commit that referenced this issue Apr 9, 2024
@otegami
doc contribution/documentation: add how to submit contribution to doc…
2289595 
… contribution guide (#1753)

Related Issue: #1733

- [x] Add the `Submit contributions` section without Japanese
translations

I will do the below tasks at the following PRs.

- [ ] Add Japanese translations about `Submit contributions`
@otegami otegami mentioned this issue Apr 9, 2024
Merged
1 task
kou pushed a commit that referenced this issue Apr 17, 2024
@otegami
doc contribution/documentation: translate how to send patch on doc co…
b34c264 
…ntribution guide (#1756)

Related Issue: #1733

- [x] Add Japanese translations about `Send patch`
@otegami otegami mentioned this issue May 13, 2024
Merged
1 task
komainu8 pushed a commit that referenced this issue May 15, 2024
@otegami
doc contribution/documentation: improve steps about send patch (#1778)
cc2494b 
Related Issue: #1733

- [x] Add the Sending patch section after Preview Your Modifications on
HTML

Consider sending a PR before the `Optional: Translate documentation`.
This approach allows non-Japanese speakers to update only the English
sections without needing to skip any parts.

ref: #1746 (comment)
@otegami otegami linked a pull request Jun 5, 2024 that will close this issue
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Feature
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

doc contribution/documentation: add an outline otegami/groonga
2 participants
@abetomo @otegami