[bisq-network/bisq-docs] Add links from intro to new getting-started doc (#59)

[Chris Beams]

@HarryMacfinned, in general, we do want to take an "optimistic merging" approach, where, so long as a change is reasonably complete and follows standards, we merge it, knowing that others can always come along and further improve it. Doing things this way avoids long delays and gets value to users more quickly.

With that said, however, we are still very much in the process of defining what complete means, and what those standards are. Once there are a good number of docs for contributors to look at and understand "where the bar is", they will have the ability to create docs that meet these standards. In the meantime, pull requests will take a bit longer, because every new one is a new case, and requires real, hard work to figure out what the right structure is, etc. I'd prefer, during this phase, to have pull requests open for a while longer than to merge them too early, because once something has been released, people have a natural and understandable tendency to move onto other things. It's extremely important right now to establish a baseline culture where everything we ship is high-quality, from software to the documentation that describes it. If we merge things too 'optimistically' before really establishing that culture, then we'll very likely end up with a culture of shoddy, mismatched documentation that goes every which-way. At this point, our documentation efforts are very much a _design_ effort. What's being designed here is information architecture as opposed to purely visual elements, but as with all design efforts, this one benefits from a high-level vision being rigorously applied and refined over time. Once the design has been expressed and tested in practice sufficiently through the process of publishing a number of useful docs, future docs contributors should find that doing the right thing is also doing the easy thing: that they can simply follow convention with the docs that have come before them, in everything from structure to voice to editorial rigor. We're not quite there yet, though, and that's why I continue to take a 'pessimistic merging' approach for now. It may be that we always take an at least semi-pessimistic approach for brand new documents, by the way; we'll just have to see how smooth we can make the process and how well we can disseminate the values that guide how Bisq documentation should be written.

With regard to contributing to works in progress, i.e. docs that have been submitted as pull requests but not yet merged, I agree that it's "a bit complicated, since the doc is elsewhere", but you can still contribute to it effectively by (a) submitting GitHub reviews on the PR and/or (b) submitting a pull request against the original pull request branch. This kind of 'nested pull request' isn't often done, but there's nothing preventing it technically, and it's something that we should all get comfortable with, as they are a natural result of taking the C4 process seriously.

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/bisq-network/bisq-docs/pull/59#issuecomment-393087671
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.bisq.network/pipermail/bisq-github/attachments/20180530/8f65dbaa/attachment-0002.html>