Writing the "Contributing rules" for the handbook

[Nirus2000]

A developer is needed to create the default rule. It is about formats, video resolutions, writing, image formats, structure, content overlays etc.

The "Contributing rules" from Portfolio Performance can serve as a template here.

[hug-sch]

Hi Nirus2000, do you mean something like a style guide? There are quite a few mentioned by Writethedocs.org.

I'm currently trying to update the PP manual. I could try to make a condensed and appropriate (for us) version of one of those styleguides mentioned above.

[Nirus2000]

Hello @hug-sch Yes, that is exactly what we are looking for. We would like to set a standard so that the manual is created uniformly. This is about video formats, light instead of dark theme, organization and structure, graphics and so on.

We would be happy if you could support us here.

Regards Alex

[hug-sch]

Hello @Nirus2000 I have started creating the style guide. You can find a beginning of it at CONTRIBUTING.md. I will regularly add to it while writing the PP manual. Please, feel free to comment.

[Nirus2000]

Hello @hug-sch starting a pull request to work together... 👍🏻

[flywire]

The project uses a https://github.com/squidfunk/mkdocs-material/discussions/2346:

Can the rules explain how to contribute different languages. For example, Is the content of the different languages a translation or is the content independent? Is there a main language with all content?

[flywire]

https://github.com/portfolio-performance/portfolio-help/blob/master/CONTRIBUTING.md#writing-setup

At present, the manual is available in two languages: English (en) and German (de).

I suggest inserting: Each language is a separate version and contributors translate the content manually.

All documentation pages should be stored within these directories; including images and assets (e.g. demo-portfolio.xml).

What about shared content? See https://github.com/squidfunk/mkdocs-material/discussions/2346#discussion-3240838

[hug-sch]

I suggest inserting: Each language is a separate version and contributors translate the content manually.

I agree. Have updated the contributing.md following your suggestion.

What about shared content? See squidfunk/mkdocs-material#2346 (comment)

The link above describes a possible solution. I'm not sure there will be many translations or extensive need for shared content between the language modules.

[flywire]

I'd emphasize markup is text, so concentrate on the content before the (simple) syntax to format it.

Go to GitHub and click on Sign up.

How about:

Sign in to GitHub (or Create an account if you don't have one).

---

https://github.com/portfolio-performance/portfolio-help#contributing seems overly complex. Perhaps something like https://dokuwiki.librecad.org/doku.php/usage:faq#can_i_easily_contribute_on_github would be simpler and adequate for most contributions?

---

https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes

Portfolio Performance Manual

Visit the manual at https://help.portfolio-performance.info or keep reading to make contributions.

For simplicity there are two types of contributions:

1. Easy: simple edit or specific section
2. Complex: typically with many files and edits

Easy

You can easily contribute on GitHub with a simple pull request (term to offer a change). For example, click the Edit on GitHub link in the top right-hand corner of any Manual page to go to the page. You will need to Sign in to GitHub (or Create an account if you don't have one) to change the files.

• Click the pencil button, search for text near the location, make any edits you want then preview them to confirm (see Hints below). Give the proposed change a description up to 50 characters and optionally an extended description then click the Propose file Change button.
• If you're reading this you won't have write access to the repository (project folders) so GitHub will create a copy of the repository (actually a branch) in your account. Click the Create pull request button.
• Give the Pull Request a description and add any comments then click Create pull request button.

Hints

Many GitHub files are in a special format, for example, the User Manual uses markdown which is just enhanced text. Codes are used to format the document so a simple search in the browser will only find text formatted the same (and Chrome would search the file but Firefox would only search the screen). If the change is simple you might be able to stay within existing formatting, try a blank line before/after the change or perhaps copy a similar formatted section from elsewhere and change it. If you mess it up get help or submit it anyway and let the repository owner fix it.

Each contribution should have its own branch so just start again. If you missed something in the pull request just open up your repository branch, change it and commit a new change.

This process will only work for one file and you can repeat it for two. If the contribution changes multiple files or has many edits use a complex contribution process described in the section below.

Managing files on GitHub

Complex

...