Revise contributor / developer docs #1924
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This doc was originally transcribed from bisq-network#511, then moved to the wiki, then moved here. Removing it now as (a) it's not clear this is of value to anyone other than the original author and (b) this approach is not necessarily something we want to advertise or promote.
The CONTRIBUTING.md file must be located in the root directory of a project (or within a .github directory) in order to be recognized by GitHub and presented to users during the process of filing an issue or pull request. It doesn't do any good within the docs/ directory.
- Simplify "What is Bisq?" description - Extract docs/build.md - Extract docs/idea-import.md - Introduce docs/README.md index
Prior to this change, DAO setup instructions and information were interspersed within dev-setup.md, making it confusing to the uninitiated reader what they need to do in order to get up and running with a basic local dev environment. All the DAO setup stuff is essentially optional, so separating it out into its own doc makes sense. Now, dev-setup.md is dedicated to the task of getting set up with a self-contained local development environment, and readers can follow the DAO setup instructions separately if and when they need to. Both docs need to be further revised and cleaned up, but that will come in subsequent commits.
For concision, idiomatic naming and to sort well with dao-setup.md.
- Remove __MACOSX dir and .DS_Store files - Rename Bisq_DAO_regtest_setup/ => dao-setup/ for consistency
- Reword headings for consistency - Polish Markdown syntax - Link to correct docs in Prerequisites section There are no significant substantive changes in the instructions here, just reworking of the existing content.
- Reword headings for clarity and consistency - Polish Markdown syntax
devinbileck
reviewed
Nov 14, 2018
devinbileck
reviewed
Nov 14, 2018
devinbileck
reviewed
Nov 14, 2018
devinbileck
reviewed
Nov 14, 2018
devinbileck
reviewed
Nov 14, 2018
|
Thanks @cbeams. This was much needed. |
|
Thanks for the review, @devinbileck. Good catches, all. |
ManfredKarrer
approved these changes
Nov 17, 2018
Merged
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR simplifies and restructures our developer documentation for ease of discovery and use. Major changes include:
dev-setup.mdanddao-setup.md, as having the two sets of instructions intermixed was a bit overwhelming and confusing.The motivation for putting these changes together was that I followed the instructions in dev-setup.md (formerly DEV_SETUP.md), and found them useful and accurate, but a bit too much with all the DAO information intermixed. That led to separating the two docs out as mentioned above, which in turn led to this more general overhaul. Altogether, I think these docs are now in good shape for guiding any new contributor in the right direction, giving them just what they need to know at each step, and hopefully keeping the instructions simple and enjoyable to follow along the way.
Note that there is now a bit of overlap between the docs here and the "contributor docs" section of https://docs.bisq.network. I think it may make sense to make docs.bisq.network our user-facing and non-dev contributor documentation portal, while keeping all things dev here. Particularly where class names, command line args and the like are mentioned, it's better to keep such docs in the repository, so as to keep things in sync with the code that's being described. Where higher-level contributor documentation, e.g. roles, proposals and compensation are concerned, it probably makes sense to keep documenting that at docs.bisq.network. /cc @m52go