search

BitcoinDesign / Guide

A free, open-source community resource for designers, developers and others working on non-custodial bitcoin products.
https://bitcoin.design/guide/
Other
455 stars 96 forks source link

Explore tech frameworks to use for the site #6

Closed GBKS closed 3 years ago

GBKS commented 4 years ago

So far we have discussed Jekyll, VuePress and Gatsby as options. They are all based on markdown content, to allow for easy editing without complex technical requirements. Let's gather the benefits and disadvantages of each one based on our goals and requirements and decide on a direction.

Slack conversation

Considerations:

johnsBeharry commented 4 years ago

With Github Actions pretty much any framework can be setup to work with GitHub Pages.

Extending on the considerations:

  1. Who is currently contributing to the codebase?
  2. Who is interested in contributing to the codebase?
  3. What tools are those contributors familiar with?
  4. What are the short term objectives of the technical team?
  5. What are the long term objectives for the site in regards to functionality?
  6. How portable is the content, and the frontend code?
  7. What would a migration strategy look like?
  8. Can the decision be postponed until a v1.0.0 is created?

☝️ It would be great to if we can get closer to a discussion before the next community call https://github.com/BitcoinDesign/Meta/issues/3, it may be difficult to schedule but we can do a series of impromptu calls with contributors to talk to one another about a direction that can be proposed to the wider community, so we can then* get consensus.

On a personal note, I see a good amount of work has been already put into the Jekyll implementation, and we should respect the time that was contributed.

I would also advise if we use .mdx or another components in markdown equivalent, that we keep the components very minimal so it doesn't disrupt the markdown editing experience and scare off potential non-technical contributors. Markdown + Github is already a far departure from their norm.

Once the Markdown files are kept minimal, we should be able to migrate between the frameworks pretty easily.

Technical skills I can contribute

ConorOkus commented 4 years ago

I support the Github actions/pages workflow, like @johnsBeharry says most frameworks support it well out of the box.

I think the thing that stands out most for me at this stage is the "Support for custom components in markdown". Although the site will predominately be text-based I wouldn't want us to corner ourselves into a framework that doesn't have this flexibility.

We can talk more about this but the technical requirements are really low e.g no databases, API management etc it's just content so I would be really fine with a few people just bootstrapping the project at least for version 1 using one of the mentioned frameworks and see how we go from there.

The design guide is the main focus for now, but we do need to think hard about how the site will evolve over time and positioning ourselves so that it's still possible for as many people to contribute as possible.

Looking forward to having this chat over a call at some point.

I do front end development mainly so would be comfortable with whatever we choose from a technical point of view 👍

GBKS commented 4 years ago

I really like the benefits of Gatsby and VuePress and could go with either one. However, I don't see any deal breakers in the Jekyll setup Pedro got started with, so I recommend sticking with it. This will allow us to go live quickly and move our focus to content.

We can still do custom components with Jekyll since Markdown allows for arbitrary HTML to be inserted. The code for those components will just be a little more elaborate than with a Gatsby/VuePress solution.

This route will allow us to better figure out what our actual IRL needs are (not hypothetical needs) and then make a better decision on a framework upgrade.

Bosch-0 commented 4 years ago

Just another option for the site - been playing around with catalog today which is a react based design system generator. I find its very simple to use and using react gives much more flexibility design wise. Also has great documentation and most editing is just done via markdown files. I think it would easy option to contribute to the guide for those designers who may be intimidated by github / jekyll etc. https://www.catalog.style/

ConorOkus commented 4 years ago

Looks pretty cool, just not sure how much design system work is needed for the design guide site. Agree its much easier to work with something that supports components.

GBKS commented 3 years ago

No action on this issue for months, so closing it out. Seems like we're good right now with our current setup using Github pages and Jekyll. We can open a new issue if there's interest in the future.