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.

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

Restructuring developer documentation for easier reach #11507

Closed
wants to merge 2 commits into from

Conversation

subhramit
Copy link
Collaborator

@subhramit subhramit commented Jul 16, 2024

contributing.md used to be an independent topic in the devdocs in itself.
Apart from having its own original content as index, we propose to make it a parent that has two children:

  1. The "Getting into the code" section. This contains:
    1a."JabRef's development strategy",
    1b."Setting up a local workspace" and
    1c."High-level documentation"
    This used to be an independent section in itself, which will be shifted here.
  2. Developer FAQs (Refer Add FAQ to devdocs (Code Howtos) #11456).

This makes important documentation more prominent to reach for newcomers.

This PR also fixes some grammatical errors in FAQs, and adds some pointers about reaching IntlliJ Settings in M2 Macs while setting up the development environment.

Update: Also adds the link to the developer FAQs in the github actions bot newcomer greeting message.

Mandatory checks

  • Change in CHANGELOG.md described in a way that is understandable for the average user (if applicable)
  • Tests created for changes (if applicable)
  • Manually tested changed features in running JabRef (always required)
  • Screenshots added in PR description (for UI changes)
  • Checked developer's documentation: Is the information available and up to date? If not, I outlined it in this pull request.
  • Checked documentation: Is the information available and up to date? If not, I created an issue at https://github.com/JabRef/user-documentation/issues or, even better, I submitted a pull request to the documentation repository.

@subhramit subhramit changed the title Shifting development documentation for easier reach Restructuring developer documentation for easier reach Jul 16, 2024
@@ -24,6 +24,8 @@ jobs:

Newcomers, we're excited to have you on board. Start by exploring our [Contributing](https://github.com/JabRef/jabref/blob/main/CONTRIBUTING.md) guidelines, and don't forget to check out our [workspace setup guidelines](https://devdocs.jabref.org/getting-into-the-code/guidelines-for-setting-up-a-local-workspace) to get started smoothly.

In case you encounter failing tests during development, don't forget to check our [developer FAQs](https://devdocs.jabref.org/contributing/faq.html)!
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Try to avoid negations: please check our instead of don't forget to...

@subhramit
Copy link
Collaborator Author

subhramit commented Jul 17, 2024

Moving to WIP till:

  • Links pointing to the moved parent topics are fixed
  • Screenshots are added in PR Description

@subhramit subhramit marked this pull request as draft July 17, 2024 22:31
@subhramit
Copy link
Collaborator Author

We will probably have to close this because: https://just-the-docs.com/docs/navigation-structure/#example-children-within-children

Currently, the navigation structure is limited to 3 levels: grandchild pages cannot themselves have child pages.

@subhramit subhramit mentioned this pull request Aug 5, 2024
6 tasks
@subhramit subhramit closed this Aug 5, 2024
@koppor
Copy link
Member

koppor commented Aug 6, 2024

Will be huge effort to finalize. Thus, better improve the Markdown files (as you did). We will do a larger restructuring at another time.

@koppor koppor deleted the documentation branch August 6, 2024 00:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants