search

mediamonks / muban

A backend-agnostic framework to enhance server-rendered HTML using a modern webpack development setup.
https://mediamonks.github.io/muban/
39 stars 15 forks source link

Add README to blocks #118

Open pigeonfresh opened 4 years ago

pigeonfresh commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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).