Skip to content
This repository has been archived by the owner on Jun 15, 2021. It is now read-only.

Add links from intro to new getting-started doc #59

Merged
merged 1 commit into from
May 29, 2018

Conversation

cbeams
Copy link
Member

@cbeams cbeams commented May 29, 2018

@bisq-network/contributors, there will likely be a number of pull requests coming into bisq-docs like this one in the near future, i.e. pull requests that I submit and then immediately merge myself. I'm doing this to make it clear that in writing a documment or making a change to one, I'm acting as a contributor, just like anyone else. When I merge the change, I'm acting as a maintainer. While in the future, these two actions will be often be performed by different people and separated by time to allow others to review, I'm submitting and merging back to back in order to expedite things, and to be pragmatic and efficient while in practice I'm one of very few making these changes.

Issuing a pull request even for small changes like this one has a number of benefits:

  1. It follows the C4 process, helping to ensure that we have processes that apply to everyone and don't require exceptions.
  2. It creates notifications that allow anyone who puts a watch on the bisq-network/bisq-docs GitHub repository to get notified about the change and to review the change (post-merge reviews are welcome!)
  3. It creates a clear record of work that I have performed as a contributor, making it easy for me to put together my compensation request at the end of the month by doing a GitHub search for issues and pull requests in the last month that involved me.

So even though these pull requests may get created and then immediately merged, please do review their content and point out any errors, or better yet follow up with pull requests that fix stuff or make it better.

I've also just created a new team, @bisq-network/docs-contributors, currently consisting of myself and @m52go as members. We can @mention this team any time we want to get the attention of docs contributors, especially when there's valuable work to be done. If you'd like to be added to this team, just ask one of the @bisq-network/docs-maintainers.

@cbeams cbeams self-assigned this May 29, 2018
@cbeams cbeams changed the title Add links from intro to new getting-started Add links from intro to new getting-started doc May 29, 2018
@cbeams cbeams merged commit 7d0f526 into bisq-network:master May 29, 2018
cbeams added a commit that referenced this pull request May 29, 2018
Add links from intro to new getting-started doc
@ghost
Copy link

ghost commented May 29, 2018

I think it is a good idea/practice to refresh the documents asap with the contributors inputs,
particularly because this in turn may help other contributors to participate.
Pull requests open for a long time helps to create a kind of jam I feel (?)
For my part, I would be happy to see the api docs coming here in bisq-docs, even in a draft/raw state, in order to help. Which is a bit complicated at the moment since the doc is elsewhere.

@cbeams
Copy link
Member Author

cbeams commented May 30, 2018

@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.

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant