Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add README to blocks #118

Open
pigeonfresh opened this issue Nov 12, 2019 · 2 comments
Open

Add README to blocks #118

pigeonfresh opened this issue Nov 12, 2019 · 2 comments

Comments

@pigeonfresh
Copy link
Contributor

I would like to suggest adding a README file to (at least) Block components. This would be a great way to (deep)link to UX, Designs, animation mockups, Marvels and/or tickets and add more clearity by adding docuentation about the block.

It could contain a small introduction about the authorable items, the options and it could show updates that have been made during the project.

It would mainly serve as a way to communicate between front- and backend teammembers or future-self.

I've created an example of how I would like to use it:

https://gist.github.com/pigeonfresh/beb0833a412bf0918941e9f8f1ca109f

@skulptur
Copy link
Contributor

skulptur commented Feb 9, 2020

Documentation adds a lot of overhead and can get stale/out of sync quite easily. I like your readme format, but would rather see that being applied to the issues/tickets themselves and have that as a single source of truth.

@ThaNarie
Copy link
Member

ThaNarie commented Feb 9, 2020

The problem with tickets is that they are spread all over the place, could have a lot of comments, might not contain enough information when created and are not updated afterwards. This makes it hard to find the information you need.

I am in favour of a document per component/widget/block, I just haven't found the perfect place for it yet. Readme in a folder works (easy to find and update), but might be harder for non-devs to update.

Having a separate document (or one per block) somewhere where everyone can find and edit them might work better (e.g. google drive / docs).

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

No branches or pull requests

3 participants