Contributor documentation

[keunes]

Short description: Add contributor documentation.

Location:

Why have this:

From AntennaPod/AntennaPod#6834 (comment):

It would be nice if there was an easy way to auto-format it according to the requirements but I didn't see anything in the contributor guide

The contributor's page for 'Develop' links to this wiki page: https://github.com/AntennaPod/AntennaPod/wiki/Code-style. Apparently it's not visible enough.

Also, the Contribute > Translations page is rather long and complicated.

More info:

Pages to include:

• Requesting new languages
• Using Weblate
• Code style
• Building AntennaPod
• About debug versions

Also to mention somewhere:

• Discussions on functionality in the Forum
• Concrete/boiled down solution descriptions in Issues
• Technical/Implementation discussions in PRs

[ByteHamster]

I'm still not really convinced that the public website should hold very technical stuff like the developer documentation. The comment linked above doesn't imply that they did not find the developer documentation. It just says that the developer documentation does not contain what they were looking for (now it does).

[keunes]

The comment linked above doesn't imply that they did not find the developer documentation. It just says that the developer documentation does not contain what they were looking for (now it does).

I didn't realise you edited the wiki page to add the info :-)

I'm still not really convinced that the public website should hold very technical stuff like the developer documentation

It doesn't have to be in the menu, confusing 'regular' users. But as a) important information for contributors is currently spread over different places and b) hard to process (at least the translations), we need to do something to address both issues.

And as our main website goal is to attract contributors and ensures a good mix of controllability and openness (using PRs, impossible combination on the wiki), I find it the most appropriate place. (But if you have another proposal that addresses identified issues, I'm all ears.)

[antennapod-bot]

This issue has been mentioned on AntennaPod Forum. There might be relevant details there:

https://forum.antennapod.org/t/project-management/3879/3

[ByteHamster]

Was your idea to completely remove the wiki and the CONTRIBUTING.md file from the main app repo to have everything in one place?

[keunes]

My idea was indeed to drop the wiki entirely. CONTRIBUTE.md probably not, as it's a recognised standard. However, if we have a contributor's section, we should limit it to key information & pointers.

[ByteHamster]

If we do this, I would limit the CONTRIBUTING.md file to just contain a link to the website. Then we really have everything in one place. Otherwise we move from wiki+repo to website+repo, so the information would still be spread over different places.

I assume the contributor documentation won't get translated, right? Translating variable naming guidelines and stuff doesn't make a lot of sense because the variables themselves should be in English anyway. Also, contributions are discussed in English as well.

[keunes]

I assume the contributor documentation won't get translated, right?

Yeap, agree.

[loucasal]

I could help with (at least parts of) these documentation pages next, starting with the translation bits.

However, I have a few questions before I set myself to the task:

• Is the migration away from Transifex going to be completed soon? That would help streamline the current documentation.
• Do you have a preference between keeping all translation-related guidance on one page vs. splitting it in multiple pages (e.g. (1) app, (2) website + other materials)?
• Why do we need to have our own documentation on using Weblate? Isn't it sufficient to point to the Weblate documentation as we currently do?
• How about the maintainer documentation on updating translations? Do you see any value in it? I would assume not.

[ByteHamster]

Why do we need to have our own documentation on using Weblate? Isn't it sufficient to point to the Weblate documentation as we currently do?

I agree. This would just mean we would have to keep it up to date.

How about the maintainer documentation on updating translations? Do you see any value in it? I would assume not.

I never used it. It's probably outdated anyway since Transifex changed their client some years ago

[antennapod-bot]

This issue has been mentioned on AntennaPod Forum. There might be relevant details there:

https://forum.antennapod.org/t/monthly-community-call/1869/71