Relocate contribution guide to the website.

[digisomni]

The contribution guide isn't necessarily a user oriented exclusively, nor does it have only developer aspects to it. It seems to be best served from the website directly. This will make it easier to update and also style to make it appealing for potential contributors.

https://vircadia.com/contribute/

[JulianGro]

I don't see how this makes updating and styling easier. People need separate accounts to work on that, while here they can just create pull requests or open issues.

[digisomni]

I am able to make it more attractive, as linked. Plus it's a bit dev-vy so it doesn't belong in the user docs either. But not so dev-vy that it should go in the dev docs. Trying to trim fat and get things where I can work on them efficiently, in this case, specifically with regards to recruiting new contributorship.

[JulianGro]

We essentially want to make users to developers, so the user docs seem like the most appropriate place. Having the same info on the website doesn't seem like a bad idea, but while it looks more attractive it really isn't functional.

[digisomni]

What do you mean by functional, exactly? As for conversions, we also want to turn developers into contributors, and the link is still there so they'll end up in the same place so users will still get the nudge. Regardless, the platform is a good match for developers at the moment so I want to continue reaching out on that front.

[JulianGro]

If we are talking about function, there is a couple of issues with that webpage.

• Text is far too low contrast and is had to read on any device I can think of.
• The page has slow animations that move it while you already want to read, making it harder to get an overview.
• A lot of vertical space is wasted by big logos that don't add anything, making it even harder to get an overview.
• There is useless clutter on the page which adds noise and makes it harder to find what you are looking for. Mainly I mean the quote on the side that is useless and also written in a hard to read font, making it harder to check if that is useful information to the viewer.
• The boxes animating in are also annoying, because the viewer has to wait for the animation to finish before being able to read them. This might not seem like much, but when I view a web page like this I already assume the next header is going to in line with the ones above. Then they show up in the middle of the screen, making me readjust, and then they move to the side again. It also, again, makes it harder to get an overview of the page because you need to wait for stuff to show up.

[digisomni]

Oh I agree that many parts need revising, I'll tackle some of those. I had only made it tonight. It'll keep getting updated as I do with all the pages. But that's part of the beauty of it, easy to revise with many complex options to play with.

[Penguin-Guru]

As of the current version, here are my comments on Julian's observations.

1. The text looks fine to me, not that I'm the best person to judge.
2. The animations aren't too slow. I didn't notice any lag the first time I opened it but I did the second time. I think the cards appearing adds enough value that the lag might be acceptable, but there should probably be a way to reduce the lag somehow. There is also a bit of lag for me when I scrolled to the top and the Vircadia title above your main nav bar resized-- this resizing is a bit rough, it jitters.
3. The only logo that seems big to me is the Vircadia logo to the right of the first paragraph, in the purple header/banner. I don't notice any particular waste of vertical space. I actually think that the spacing between the sectional cards has a positive effect of making the content seem more meaningful and making the page a good length.
4. I see you moved the quote card to the bottom of the page, so it's not sticking off on the right. There might be better options but this seems fine to me. The are only things that make the page feel cluttered or messy to me. The first is that the cards overlap the borders between the background changes (i.e. purple to white at the top and then white to grey at the bottom). The second is that the cards are all offset to the left, except the quote card at the bottom. I assume this is because you wanted them justified with the non-card text in the purple header/banner.
5. I don't think the card animations are a significant problem, but you could probably accelerate the animation slightly to make them readable slightly earlier. I'm not sure what that would look like. Since Julian said they appear in the middle of the screen, I'm guessing this was adjusted. For me, they appear near the bottom.

My general opinion is that putting this page on the main site is much more organised, since this is where people will expect to find it, it reduces clutter in the specific docs, and it doesn't have to be maintained in an arbitrary repo. This is not a page that should need to be updated very often and I don't think there should be much benefit to encouraging people to contribute to it. Of course, anyone who has feedback on the site should be free to provide that feedback, but it's not necessary to put everything in git. As much as I like the style of the user docs, I think this new layout looks good and works very well for the Contribute page. The content could probably be improved a bit more.

[digisomni]

Otherwise, the syntax appears to be fine and there are no warnings reported by the checks. Anything seem off?

[JulianGro]

I guess I just don't like having stuff removed from the docs that has its place there. It's just annoying to the end user if they want to look at the contribute page and the contribute page actually only contains a link to an external contribute page. There isn't really anything to go outdated there either, so keeping both pages isn't really a maintainance concern either.

[JulianGro]

That Weblate push just reminded me that there is another reason why this should be in the docs: https://docs.vircadia.com/fr/contribute.html https://docs.vircadia.com/es/contribute.html

Considering we have full translations for this on the docs, and the website doesn't have good (or currently any) translations support, I am rejecting this PR. I don't see why we should inconvenience the readers and exclude non-english speakers (especially since the translation gets suggested as a way to contribute) for what is at best a miniscule maintainance improvement.

[Penguin-Guru]

Good point. I think it's a significant improvement to add that page to the main site, but not worth losing the translations. I suppose the best options would be to apply the translations to the main site or maintain the information in both places. Either way would probably be a nuisance but I'm no web dev.

[digisomni]

Because the user docs should be primarily focused on delivering, well, documentation on how to use the platform for the user. Currently, it takes on too much outside of that purely for the sake of translation (which is understandable, to an extent). Regardless, trimming is needed. Similarly, the developer docs are meant to advise and inform developers on how to use/implement the platform correctly.

As for having two copies, there shouldn't be odd copies laying around that might conflict or confuse, there were numerous issues in the page already for example. I update and revise verbiage regularly, going through Git makes this process a lengthy process to do often, especially where appealing to new users and contributors is involved.

Translation wise, I've added some translation support to the website. Check it out (top right of the screen): https://vircadia.com/contribute/

Ultimately, I don't think user-generated translation (as opposed to existing translation tools) is a good enough reason to try and replicate all material relating to Vircadia in the user docs.

[JulianGro]

My side of things still stands. There is no "trimming down" needed, if there was any issues they can be reported, an automatic translation is no replacement for a proper human-made translation, and the reason we do use git and do PRs is so people can check stuff before it gets changed.

[Penguin-Guru]

Maybe it would be good to have a review process for changes to the main website? For example, versioned changes could be hosted to a testing sub-domain and then a certain amount of time could be waited to accept comments. Some changes, like to the style or the content, could require approval from some number/percentage of people, maybe during community meetings if it should be formal. This kind of process feels a bit too bureaucratic to me but it's an option.

[digisomni]

I'm only really going to need that once all of this outgrows me and I delegate more duties. Currently, I need full versatility over user-facing things such as branding, marketing, etc. and I can keep track, so there's no need for any such processes at the moment.

[Penguin-Guru]

I think that's fine for now, as long as other people are fine with it, but you might still want to use that kind of testing sub-domain and version control for testing and getting opinions on stuff. Something to consider.