Cross the stream

[ansuz]

This PR attempts to deal with the huge mess that resulted from people making PRs to cjdns/docs instead of here.

There were a lot of collisions, which I did my best to fix.

Apparently, I accidentally pulled in the cjdns codebase while trying to do the subtree merge described in the contributing document. The subtree split didn't work because of dangling commits that I was unable to fix.

If we're going to merge this, I suggest we squash it and throw away all that history. Before doing so, there's a lot of stuff to review. I greatly appreciate any help that people can offer in this regard. Please make use of github's new code review features!

Thanks!

[kpcyrd]

Are you sure we don't want to just drop the docs out of the repo? The workflow of squash and merge is pretty smelly and causes issues like this.

We should also define some processes if we want to keep this, like automatically rejecting edits on cjdns/docs and automatically merge the docs back into the main repo periodically.

[ansuz]

• Non-code PRs to cjdns generally get merged, as they won't break builds. This means they get almost no review.
• Merges can also take a long time (certainly longer than in this repo).
• Putting things in cjdns/docs gives us little autonomy to reorganize things (because that means a bigger patch that's harder to review)

Currently we have a website that should be displaying these docs (docs.meshwith.me). I think most beginners would appreciate a website that features instructions, if the site were organized in a sensible way.

Keeping the docs alongside the code has some benefits, but I think there are enough drawbacks to make it not worth it.

We had better community involvement before we introduced the difficulty of having to merge back and forth, and the community is significantly larger now. I think if we lower the barrier to entry again, we'll get back on track with presenting up to date documentation.

But, if nobody reviews this, I'll assume that those assumptions are incorrect, remove this repo, and put no more effort into documentation.

Perhaps somebody will make a website that builds from cjdns/docs, or the masses will be overwhelmingly satisfied with a messy folder tucked into their cjdns.git's doc/.

[ansuz]

@cjdelisle @lgierth @thefinn93

[inhies]

Didn't review it but it's git, if something is missing or was wrongly deleted, we can get it back. This is a huge update and I thank ansuz for putting in the work to get this repo up to date.

I think we should work to keep this repo as the de facto source for cjdns docs. Maybe cjdns should have some kind notice directing contributors to submit pull requests on this repo if they want to contribute.

Basically, squash this, merge it, and continue onward and upward!

[kpcyrd]

imo, the following things should be done regarding documentation:

• cjdns/docs should be moved into this repo and then deleted from the code repo
• the readme in the core repo should be shortened since it duplicates parts of the docs and are frequently out of sync
• translations should live in this repo only
• the docs website should be maintained by a team of people so things like "automatic rebuild" aren't blocked by a single person

This would significantly reduce noise on the core repo

[ansuz]

07:39 <@cjd> maybe you just be concerned with keeping that docs repo up to date and I'll either merge it or send people there

[ansuz]

YOLO