Design Guide Individual Page Structure & Content/Contribution Gudeilines

[pavlenex]

There are plenty of people from all around the internet contributing to the design guideline. As a result, the structure of the pages varies. While it's impossible to standardize everything, I would like to propose that we try to improve the contribution guide that would help new and current contributors better understand "how we work".

Such document should help with defining:

• Target audience Define audience for the guide #51
• Tone and Terminology - Good example we also have this in the Design Guide, but should probably have it in our contribution guide )
• Visual consistency
• Basic structure (below is just an example)
  • Getting Started
  • Design Fundamentals
  • Principles
  • Case studies
• Technical information depth (Another issue I'd like to discuss is how in-depth do we go into technical details)
• Visuals vs Text and how we determine the ratio of visuals vs text)

IMO a structured contribution guideline would make reviews easier and help us define structure we want for the guide.
Some of these can be structured into Contribute.md but also added as a pull request template checklist when someone creates a new pull request.

Opening this up for discussion here, just some food for thoughts. I'm happy to take over this task, but since I'm relatively new, I'd need help with figuring out how to define the things outlined in the bullet-points above.

[danielnordh]

Thanks for bringing this up.
Happy for you to take a lead and propose something here.

I'm particularly interested in the basic structure and information depth handling parts.

[pavlenex]

Daniel, I think what you did with Private Key Management can be a great basis for the contribution guideline.
Drawing a line between information depth and visualization is something we certainly need to figure out.
I'm happy to begin drafting something once we have more feedback and consensus to proceed.

[GBKS]

Getting the impression that we may need a "Contribute" section with the following pages (or something similar):

• "Introduction"
• "Target audience" (started)
• "Content guidelines" (done)
• "Illustration guidelines"
• "Formatting" (done)
• "How to submit"

This should also be clearly different than contributing to the design community in general.

The pages we have are floating around in "Resources", but that's really not the right place.

[pavlenex]

That's a good structure. Should we rename the "Resources" to "Contribute" and build on it? Resources were a bit confusing and I am just now seeing that sections you've mentioned as done already exist as a part of the guide. If we do that, is the goal of that page teaching people how to contribute, and if it is, what do we do with Contribute.md then?

Usually sections that involve contribution are call "Contributing" or "Get involved". Resources seems like a resource for bitcoin application builders to me, rather than contributors

My suggestion:

• Re-structure Contribute.md and merge good info from Resources into it
• Re-name the section to Get Involved or Contribute
• Work on rest of the sub-sections (pages)

Once finished, ideally it would have clear outline on how to contribute, write, what tone to use, preferred structure and formatting etc

[GBKS]

I don't see an issue there. "contribute.md" (bitcoin.design/contribute) is about the community in general, while the "Contribute" section (bitcoin.design/guide/contribute) is about helping with the guide project. So they cover two distinct topics. Some people want to do bitcoin design stuff in general, others want to work specifically on the guide. Does that make sense?

[pavlenex]

You're right, it does make sense. Should we still call this section "Resources" though or not?
I'm happy to take on this task and try to define some standards on how to contribute to the bitcoin design based on suggested structure and ideas.

[GBKS]

Resources was just a placeholder, we should change it to "Contribute". Thank you for your initiative.

[pavlenex]

@GBKS I've been thinking about your suggested structure, and it's great but imo it's missing an important part, concrete "how to contribute" to the guide. There we can outline the process of doing a PR and maybe add videos I've made. How would we call such section, where do you suggest we put the content? Or is that what you mean by "how to submit", in that case do we have a better name 😸 ?

[GBKS]

I was thinking we split that across the "Introduction" and "How to submit". The former more generally about contributing (finding a topic, talking to people, research, etc) and the latter about the Github/PR/review process and a pre-review checklist. But if we write this stuff out and there's a better page structure, then let's use that.