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

Add instructions and example of how to create Pull Requests for documentation #627

Open
2 tasks done
cookiemonsteruk opened this issue Nov 4, 2024 · 1 comment
Open
2 tasks done
Labels
support Community support

Comments

@cookiemonsteruk
Copy link

Important notices

Before you add a new report, we ask you kindly to acknowledge the following:

Is your feature request related to a problem? Please describe.
This is not a report of a problem.
A clear and concise description of what the problem is including your motivation for the request,
i.e. "For the purpose of [...] I am missing a solution that will [...]."
The current suggestions in the documentation on how to contribute to the documentation itself is insufficient to get a new contributor started.
Describe the solution you like
I'd like to see the current documentation expanded to the point where someone who is new to github and OPNSense can create a new PR for documentation.
A clear and concise description of what you want to happen.
Expand the documentation and provide a step by step with an example to get from zero to PR.
For context, this does not get anyong going:

Documentation & wiki articles

The easiest way to help with documentation is to write how-to type articles. As the wiki & documentation project itself is written in reStructuredText you can offer your content in this format (preferably as a [pull request](https://github.com/opnsense/docs)). Other formats are also possible, such as:

    markup with ./images/directory including the used images (if any)

    word document with embedded images (if any)

To include you documentation send it to contact @ opnsense.org. Make sure that:

    Your content does not include copyrighted material if you do not own the copyright yourself

    State that we may use the content under our Documentation Copyright as listed in the [Legal notices](https://docs.opnsense.org/legal.html) section.

Of course we can "just send to OPNSense to include" but wouldn't it be better to submit a PR ourselves?
Additionally the docs of the docs themselves ie. this repository https://github.com/opnsense/docs:
has "Prepare build", "Update API endpoints", "Generate HTML documents" and "Live preview of HTML documents". At no point this explains how to create our new document or changes to existing one, to the point where a PR can be submitted.

Describe alternatives you considered

Submit a word processed document on email or post to forum. Help us be of more help.

Additional context

I and sure others too, would like to contribute to the documentation. It would be good to lower the complexity for non-developers. Some people will be happy to learn a new skill that is closer to IT development ie. using github version control, create some content, create a PR. Win-Win.

@Monviech
Copy link
Member

Monviech commented Nov 4, 2024

Isn't this more in the scope of general github documentation?

https://docs.github.com/

  1. https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo
  2. https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork

Here is some sphinx documentation for using restructured text:

https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html

I have used sources like these when I was new on github and didnt know how to use restructured text.

@Monviech Monviech added the support Community support label Nov 7, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
support Community support
Development

No branches or pull requests

2 participants