Add 'how to contribute' content + styleguide

[RCheesley]

This used to be on the docs, but maybe it sits better in the Community handbook (contribute.mautic.org)?

Either way, we should have it loud and proud on the landing page, how to contribute!

Note for redirects:

https://docs.mautic.org/en/contributing/style-guide https://docs.mautic.org/en/contributing

[Timonwa]

Hi @RCheesley, can you give more explanation on what this issue is about? And how I would go about it if I were allowed to contribute to this.

[RCheesley]

Hi @Timonwa and thanks for being willing to help out! Apologies for the brevity of the description!

Currently on the user documentation, we don't have anything telling people how to contribute to the documentation. We used to have a style guide and a contributing page.

My thoughts out loud were that perhaps we should have those docs in the Community Handbook (https://contribute.mautic.org) rather than on the docs itself, and simply link out to those resources. The repo for the Community Handbook is here: https://github.com/mautic/mautic-community-handbook.

So what I suggest is:

1. Review the contributing page and the style guide from the old docs, and determine what's still relevant, what needs updating (e.g. we now use Vale, and RST on Read the Docs so that needs including).
2. Make a PR to include these docs in the Community Handbook under the Contributing to Mautic section. I think we should make a separate section for 'documentation' and we should explain both the end-user and developer docs. They use the same platform (Read the docs) but have different ways of working. Let's start with the end-user docs but have in mind we should add the dev docs in the future. Note also there's a small part about technical writers https://contribute.mautic.org/contributing-to-mautic/writer#technical-writers which we could move to this new section or perhaps signpost from there to the new page
3. Make a PR on the end user docs (this repo) which explains how people can contribute, and links out to the newly created pages.
4. Edu team set up redirects from the two links posted in the description, to the new content

Hope that makes sense, @mautic/education-team-leaders might chime in if they have some further thoughts!

[Timonwa]

Thank you, @RCheesley. This makes more sense now. I can work on this. However, I might need help knowing what information to update or remove. I could figure some out while contributing to or moving the documents, but I still need help ensuring all the details are current.

1. To confirm, I would add the Contributing and Style Guide pages to the Contributing to Mautic section.
2. I am unsure which pages on the Community Handbook fall under the end-user and developer docs, so I can't share my thoughts on this.
3. Since the Technical Writer section talks about contributing as one, I think it is still okay to be under the Writing for Mautic section.
4. Concerning moving the Technical Writer to a new page. Is the style guide and the content on the Writing for Mautic section the same for both Technical and Content/Marketing writers because I can see that a writer can fall into either category? If both share the information, then we can break down the 'Writing for Mautic' section into sub-pages like the general info, then specific info to contributing as a content writer and as a technical writer, and then move the style guide into it since it was would just be used by the writers anyway.

Let me know your thoughts.

[RCheesley]

Handing this over to @mautic/education-team-leaders who can give you a steer on this!

[favour-chibueze]

Thank you, @RCheesley. This makes more sense now. I can work on this. However, I might need help knowing what information to update or remove. I could figure some out while contributing to or moving the documents, but I still need help ensuring all the details are current.

1. To confirm, I would add the Contributing and Style Guide pages to the Contributing to Mautic section.
2. I am unsure which pages on the Community Handbook fall under the end-user and developer docs, so I can't share my thoughts on this.
3. Since the Technical Writer section talks about contributing as one, I think it is still okay to be under the Writing for Mautic section.
4. Concerning moving the Technical Writer to a new page. Is the style guide and the content on the Writing for Mautic section the same for both Technical and Content/Marketing writers because I can see that a writer can fall into either category? If both share the information, then we can break down the 'Writing for Mautic' section into sub-pages like the general info, then specific info to contributing as a content writer and as a technical writer, and then move the style guide into it since it was would just be used by the writers anyway.

Let me know your thoughts.

Thank you for reaching out and for your willingness to contribute to the improvement of our documentation for Mautic.

Regarding your points:

1. Adding Contributing and Style Guide to Contributing to Mautic: Yes, including these pages in the Contributing to Mautic section is a step in the right direction. Consolidating this information will make it easier for contributors to access the necessary guidelines and resources.
2. Determining Pages for End-User and Developer Docs: We can review the content of each page in the Community Handbook to determine whether it's more relevant to end-users or developers. End-user docs typically cover how to use Mautic, while developer docs focus on contributing to and extending Mautic's functionality. If you're unsure about specific pages, we can review them together to make a decision.
3. Placement of the Technical Writer Section: Keeping the Technical Writer section under Writing for Mautic is a logical decision, especially if it covers contributing aspects. However, we should review the content to ensure that it aligns with the overall structure and purpose of the documentation.
4. Style Guide and Content for Technical and Content/Marketing Writers: Your suggestion to break down the Writing for Mautic section into sub-pages for different types of writers is a sound approach. This will allow us to provide targeted guidance to each audience while avoiding overlap in content. We can review the style guide and content to ensure that they meet the needs of both technical and content/marketing writers. Here's how I suggest we approach this:

• General 'Writing for Mautic' Section: Keep information relevant to all writers here (project goals, overall style, etc.)
• Sub-Pages: Create sub-pages for "Contributing as a Content Writer" and "Contributing as a Technical Writer." Here we can discuss the specific skills and focus areas needed for each role.

@RCheesley @fakela, if you have any additional suggestions on how we can further enhance this, please feel free to share them.

[Timonwa]

Hi @favour-chibueze, thanks for your comment and clarification. I can go ahead and work on the pages now. Once I am done with that, we can further discuss how to go about "For Determining Pages for End-User and Developer Docs".

[favour-chibueze]

Hi @favour-chibueze, thanks for your comment and clarification. I can go ahead and work on the pages now. Once I am done with that, we can further discuss how to go about "For Determining Pages for End-User and Developer Docs".

Sure, you can reach out if you need help.