Best practices, initial version

[sergey-shandar]

This is an initial version. I plan to add more best practices, especially related to coding.

Should we split the document into multiple, such as "generic", "Rust", "Git"? If yes, I can do it in the next PR.

Here's a preview of the document.

[wileyj]

It would be helpful if we can create an example repo that follows the rules you're suggesting here. Otherwise, some minor suggestions on my end but overall looks great, thanks!

[wileyj]

I agree with the principles outlined here. This document is currently detached from the rest of the documentation. I suggest adding it under a Contributing section in SUMMARY.md. A way forward would be to add more contribution guidelines, including PR review guidelines which should point to these best practices.

Hmm, i would argue this document should be standalone - but i like the idea of linking to it from SUMMARY.md

[netrome]

I agree with the principles outlined here. This document is currently detached from the rest of the documentation. I suggest adding it under a Contributing section in SUMMARY.md. A way forward would be to add more contribution guidelines, including PR review guidelines which should point to these best practices.

Hmm, i would argue this document should be standalone - but i like the idea of linking to it from SUMMARY.md

If it's standalone I think we should find another repo for it since this repo is dedicated for the sbtc-docs at https://stacks-network.github.io/sbtc-docs/

[wileyj]

I agree with the principles outlined here. This document is currently detached from the rest of the documentation. I suggest adding it under a Contributing section in SUMMARY.md. A way forward would be to add more contribution guidelines, including PR review guidelines which should point to these best practices.

Hmm, i would argue this document should be standalone - but i like the idea of linking to it from SUMMARY.md

If it's standalone I think we should find another repo for it since this repo is dedicated for the sbtc-docs at https://stacks-network.github.io/sbtc-docs/

maybe i'm missing something - but the current format of https://github.com/stacks-network/sbtc-docs/blob/master/src/SUMMARY.md is to just link to other documents. what i read in your comment is that the document being PR'ed here should be added to that SUMMARY.md file (not as a link, but as raw text). I agree it should be added to that file, but my comment was more that it should just be a link to the document here, vs copying the markdown directly to that file (please correct me if that assumption is incorrect).

Moving this document is also an option - we have the https://github.com/stacks-network/stacks repo where it could live, but i would still say it should be linked from SUMMARY.md.

[netrome]

maybe i'm missing something - but the current format of https://github.com/stacks-network/sbtc-docs/blob/master/src/SUMMARY.md is to just link to other documents. what i read in your comment is that the document being PR'ed here should be added to that SUMMARY.md file (not as a link, but as raw text). I agree it should be added to that file, but my comment was more that it should just be a link to the document here, vs copying the markdown directly to that file (please correct me if that assumption is incorrect).

Moving this document is also an option - we have the https://github.com/stacks-network/stacks repo where it could live, but i would still say it should be linked from SUMMARY.md.

So what I'm saying is that the document should be linked in SUMMARY.md. If it's not linked in that file, it's not going to be rendered in the documentation when served with mdbook.

[sergey-shandar]

1. How do we expect to use this document and what is the tangible outcome we'd like to see?

I've added an additional paragraph that describes the intent of the document.

2. It would be nice to split these standards into separate documents.

In one of the next PR: https://github.com/stacks-network/sbtc-docs/issues/83

4. The I/O Section could use more concrete details

I'm trying to keep it simple and short in the document but I'm working on an article I/O is a virus and would like to publish it in multiple places to get feedback from the broader community.

@AshtonStephens feel free to re-review and don't hesitate to open issues so we can make changes incrementally

[sergey-shandar]

@stjepangolemac , @jferrant

https://github.com/stacks-network/sbtc-docs/issues/84

[AshtonStephens]

Closing because this wasn't changed and doesn't have a clear purpose.