Github repo + wiki vs just Github repo

[albertein]

I think having information on both a github repo and a wiki makes it harder for people to find information and deciding on where to put resources.

There should only be a single place where people look for information.

Pros on having everything on a git repo:

• Single place to look for resources
• Easy to discuss changes

[legtzp]

I like the idea of having everything on the repo, it also serves as a best practice exercise with PR's for the new hires. Maybe we can add one more step to the onboarding process which would be to add a new resource or content to the technical onboarding doc, being that their first PR.

[legtzp]

At least that way we can secure the involvement of new hires in the wize docs.

[rpfernando]

I like to have everything on the repo but we need to make a set of "rules" of what goes in the repo, for example facilities information (IMO) shouldn't be part of this repo, because it's only engineering related stuff.

[albertein]

I like the idea of encouraging new hires to make a pr to amend the onboarding information when not current or missing information needed.

[codinronan]

If we go from experience of what has happened before, putting things ONLY in the repo has basically meant not putting things at all. The high level of friction to get something finally merged to master has, several times, left PRs open for several months instead of simply creating some documentation and updating it later.

I think there is value in having both. It is critical that we be able to quickly dump information somewhere that can be shared and update it easily. Not everything requires the formality and level of effort of a PR. @bobmazanec

[codinronan]

Just to be clear, I'm not sure I understand the focus on "a single source of truth". We had this discussion in Phoenix and the point was made that not everyone uses Github. There are others besides engineers involved, for example, in the hiring process. Are we proposing that they MUST use PRs in order to participate in the documentation for hiring that we have in the wiki? Granted they usually use Google documents but I don't want to forcefully shut them out of the process either.

There is a case to use both. Unless we find that using both is causing significant problems, I see this as a solution looking for a problem, not the other way around.

[legtzp]

@ronanwize I agree with you about the hr people trying to contribute. I talked with Ale Pinto throughly about this, we agreed to put the technical onboarding document on github instead of google docs (The document started on a google doc) because we thought it would be more appealing for engineers to contribute to it.

[albertein]

That goes into what padilla said, the content of the wiki/repo should be only engineering related and we should optimise for engineers.

[codinronan]

Even still, as an engineer when my time is limited and I have a choice between submitting a PR for a piece of documentation, or using the wiki - I'll pick the wiki, if it is important it be documented. Otherwise I probably won't go to the effort at all.

I like Bob's distinction between "law" and "advice", API documentation is generally "law", an API-in-progress is usually advice.

Another way to look at it: If Wikipedia had been PR based it would probably have never taken off. Do we value more the discussion and the opportunity to veto a submission, or having the documentation at all? We're not really talking about code here, just info like onboarding stuff, interviewing - stuff that doesn't need to be 100% correct and reviewed.

With that I'll bow out, I want to see what others in the various teams think :)

[legtzp]

I think the most important part and the one most of engineers go through is that due to the effort it takes to contribute, almost nobody does it :/

[bobmazanec]

https://github.com/wizeline/wize-docs/issues/55#issuecomment-244792029

for example facilities information (IMO) shouldn't be part of this repo, because it's only engineering related stuff.

why do you assume/believe this repo is (should be?) "only engineering related stuff?"