Add new tutorial - "Anatomy of a CID" #359

zebateira · 2020-01-27T18:27:55Z

Closes #329
Closes #364

carlbordum · 2020-01-28T19:31:07Z

I just worked through this tutorial and it is great! I encountered no issues. I have submitted #361 that changes stuff a bit when I had to read it twice or noticed an inconsistency.

On lesson 03, IPLD is mentioned with no further explanation or references. Is this good?

The infographics are very nice, but I think they may have accessibility issues for people who suffer from reduced vision, color blindness or blindness. This is probably out of scope for this pull request, but I thought I would mention this.

Have a nice day and thanks for this tutorial :- )

zebateira · 2020-01-30T09:50:40Z

@carlbordum

I just worked through this tutorial and it is great! I encountered no issues. I have submitted #361 that changes stuff a bit when I had to read it twice or noticed an inconsistency.

Merged 👌

On lesson 03, IPLD is mentioned with no further explanation or references. Is this good?

Hm, indeed, maybe it would be nice to have a short sentence and reference link to contextualize it better.

The infographics are very nice, but I think they may have accessibility issues for people who suffer from reduced vision, color blindness or blindness. This is probably out of scope for this pull request, but I thought I would mention this.

The images should have an alt attribute. Does it need something more?

Thank you again for your contributions 🙏

carlbordum · 2020-01-31T09:12:14Z

Honestly, I don't really know much about accessibility (will read up, it's important!). When I did my review, at first I didn't rebuild, so the pictures didn't load which made me realise the difference. So that's why I mentioned it

zebateira · 2020-01-31T10:23:32Z

Honestly, I don't really know much about accessibility (will read up, it's important!). When I did my review, at first I didn't rebuild, so the pictures didn't load which made me realise the difference. So that's why I mentioned it

I see, but in that case you should've seen the alt text displayed instead, no?

carlbordum · 2020-02-01T12:34:22Z

I see it after rebuilding :-)

zebateira · 2020-02-03T09:30:32Z

I see it after rebuilding :-)

Ah ok.
@terichadbourne let me know what you think, but I think the alt text should be enough.

terichadbourne

@zebateira This is looking great! Thanks so much for pulling it together!

I did submit a commit with some proposed wording changes for clarity and would appreciate you taking a close look to confirm I haven't misinterpreted anything and changed the meaning unintentionally. Please don't hesitate to push back on any edits that don't make sense to you. I also added this tutorial to the resources and text of the Decentralized Data Structures tutorial and adjusted your Lesson 1 text to recommend reviewing the basics there before starting here. And I fixed the shortname display so it will show as "Anatomy of a CID" instead of "Anatomy Of A Cid."

For the most part, I liked the wrong answers you provided for multiple choice questions, but there were a couple spots where they felt a little forced and one I just didn't understand (see the separate in-line comment). When @alanshaw goes through this he may have ideas of common misconceptions that can be substituted in for a couple of these.

Throughout the tutorial, it feels odd to me when there are references to "which encoding was used" instead of "which encoding method" or "which type of encoding." I don't know if that's a genuine concern or is a matter of my technical vocabulary not being up to snuff. I haven't edited these spots because I'm not confident enough to do it, but maybe @alanshaw can weigh in when he reviews this.

It also feels really awkward that we need to keep referring to CIDs of certain versions - essentially "a Version 0 CID" would be "a CIDv0 CID," which is repetitive. Maybe there are spots where we should replace CID with hash to make it smoother. For now I've just replaced "version zero" with "Version 0," etc. Again @alanshaw may have suggestions on how people talk about this in prose without sounding odd. 😂

Re the alt tags for accessibility: a lot of the images we're using here are easier to understand in picture form that they would be in writing, but if something is super brief, like the string form examples in lesson 5, it's possible we could put the whole text (Qm.... Bafy....) in the alt tag so nothing's getting lost. I'd recommend just taking a spin through the full tutorial to ensure anything essential from the content of the pics is either spelled out in the alt tags or covered in the text that follows.

A couple of more logistical issues I see:

The resources page for the tutorial isn't being checked off as complete in the table of contents after I visit it, and I have the same issue with some but not all of the other tutorials on this branch. May be a pre-existing problem based on lesson type?

I don't recall if there was a reason we couldn't use marked in the multiple choice answers. It would be ideal to allow the use of code blocks with `` here but I quickly tried it and it interpreted them literally as text.

src/tutorials/0006/03.vue

src/tutorials/0006/05.md

zebateira · 2020-02-05T12:11:25Z

@terichadbourne

I pushed some edits myself after reviewing your review (accidentally stumbled upon several repeated 'the' the the so that's included as well). Let me know if it makes sense.

Throughout the tutorial, it feels odd to me when there are references to "which encoding was used" instead of "which encoding method" or "which type of encoding." I don't know if that's a genuine concern or is a matter of my technical vocabulary not being up to snuff. I haven't edited these spots because I'm not confident enough to do it, but maybe @alanshaw can weigh in when he reviews this.

Good question. Encoding refers to the representation of the data, that's why I didn't use "method" or "type, but maybe "type" could be a valid one. @alanshaw ?

It also feels really awkward that we need to keep referring to CIDs of certain versions - essentially "a Version 0 CID" would be "a CIDv0 CID," which is repetitive. Maybe there are spots where we should replace CID with hash to make it smoother. For now I've just replaced "version zero" with "Version 0," etc.

Yes, this is much better 👌

The resources page for the tutorial isn't being checked off as complete in the table of contents after I visit it, and I have the same issue with some but not all of the other tutorials on this branch. May be a pre-existing problem based on lesson type?

We were able to reproduce this for production even. Created issue in #368

I don't recall if there was a reason we couldn't use marked in the multiple choice answers. It would be ideal to allow the use of code blocks with `` here but I quickly tried it and it interpreted them literally as text.

Yeah, we should enable this if we can. Issue created here: #364

src/static/tutorials.json

src/tutorials/0006/01.md

src/tutorials/0006/03.vue

src/tutorials/0006/04.md

src/tutorials/0006/04.vue

src/tutorials/0006/05.vue

src/tutorials/0006/06.md

Co-Authored-By: Alan Shaw <alan.shaw@protocol.ai>

terichadbourne · 2020-02-12T16:51:05Z

Just chatted with @alanshaw about this grammatical concern of mine...

Throughout the tutorial, it feels odd to me when there are references to "which encoding was used" instead of "which encoding method" or "which type of encoding." I don't know if that's a genuine concern or is a matter of my technical vocabulary not being up to snuff. I haven't edited these spots because I'm not confident enough to do it, but maybe @alanshaw can weigh in when he reviews this.

He said that for someone technical it is totally fine to refer to "the encoding" as @zebateira did, and also totally fine to use my suggestions of "the encoding method" or "the type of encoding," but since we want to air on the side of accommodating less technical learners, we may as well go with my suggestions that will appear more grammatically correct to the newcomer. :)

terichadbourne · 2020-02-27T00:35:31Z

Flagging two suggestions from a Slack convo w/ @mikeal & @ribasushi today:

change <ipld-format> to <ipld-codec> when spelling out the various prefixes (@ribasushi has already suggested some in-line edits)
change this whole tutorial from being labeled as IPFS to being labeled as Multiformats (we’ll need to add the project logo, fix the project metadata, and rework some of the text )

I haven't had time to go through all of @ribasushi & @johnnymatthews edits yet but really appreciate all the feedback!

zebateira · 2020-02-27T12:13:42Z

change this whole tutorial from being labeled as IPFS to being labeled as Multiformats (we’ll need to add the project logo, fix the project metadata, and rework some of the text )

@terichadbourne added support for multiple projects in #396 which should address this partly. Only missing the text I think.

* fix: mark resources "lesson" as passed on page mount (#375) * fix: mark resources "lesson" as passed on page mount * pass lessonId to countly for resources Co-authored-by: Teri Chadbourne <terichadbourne@users.noreply.github.com> * distinguish btw file upload v code except in icon component * test reset code functionality * BROKEN test all lesson types w/ cheats * fix(content): cryptographic typo (#379) Closes #377 * Update cypress/integration/tutorials.spec.js Co-Authored-By: Zé Bateira <jose.bateira+git@moxy.studio> * Update cypress/integration/tutorials.spec.js Co-Authored-By: Zé Bateira <jose.bateira+git@moxy.studio> * chore(docs): some boilerplate updates with the new options (#376) * chore(docs): some boilerplate updates with the new options * edits to exportable properties documentation * chore(docs): update docs with the role of modules in the option * typo fix in modules description * Update src/tutorials/boilerplates/boilerplate-code.js Co-Authored-By: Zé Bateira <jose.bateira+git@moxy.studio> Co-authored-by: Teri Chadbourne <terichadbourne@users.noreply.github.com> * debug/refactor loop through all lessons * update gitignore of .env files * protect .env * test resetCode only once per lesson type * test landing pages and headers while looping through lessons * test: tutorials page displays all in correct order * test: featured tutorials shown in correct order on homepage * fix toggle and add test for hiding coding tutorials * lengthen cypress timeout * tweak test names * reinstate loop through codeless tutorials * WIP add mult choice test * fix import of lesson.js file * fix test of choice count * WIP test right/wrong answers for mult choice * refactor test descriptions * fix: eslint config for cypress * fix: test text for markdown parsing is present in quiz component * Increase Cypress tests to check reset code and loop through all lesson types (#378) * distinguish btw file upload v code except in icon component * test reset code functionality * BROKEN test all lesson types w/ cheats * Update cypress/integration/tutorials.spec.js Co-Authored-By: Zé Bateira <jose.bateira+git@moxy.studio> * Update cypress/integration/tutorials.spec.js Co-Authored-By: Zé Bateira <jose.bateira+git@moxy.studio> * debug/refactor loop through all lessons * protect .env * test resetCode only once per lesson type * test landing pages and headers while looping through lessons * test: tutorials page displays all in correct order * test: featured tutorials shown in correct order on homepage * fix toggle and add test for hiding coding tutorials * lengthen cypress timeout * tweak test names * reinstate loop through codeless tutorials * refactor to loop through lessons from tutorials util * improve viewSolution test and refactor loop through tutorials * appease linter Co-authored-by: Zé Bateira <jlageb@gmail.com> * incorporate review feedback * add test for progress status (failing correctly) * fix: lessonPassed - update UI with storage * test progress icons Co-authored-by: Zé Bateira <jlageb@gmail.com>

terichadbourne · 2020-02-27T21:48:29Z

Quick update after a chat with @ribasushi:

His suggestion is that in this image, the 128 should say 32 and that the whole colored section labelled as 2 should be gone (the beginning of the hash itself is what would come next):

ribasushi · 2020-02-27T21:57:06Z

His suggestion is that in this image, the 128 should say 32 and that the whole colored section labelled as 2 should be gone (the beginning of the hash itself is what would come next):

And ideally the bits should also express 32, or 00100000.

I want to stress again that I understand that the schedule is tight, and there is a number of images to fix. As long as the group makes an informed decision to leave things as-is, having understood the mismatch: I am fine with this 😸

alanshaw · 2020-02-27T23:07:08Z

His suggestion is that in this image, the 128 should say 32 and that the whole colored section labelled as 2 should be gone (the beginning of the hash itself is what would come next):

And ideally the bits should also express 32, or 00100000.

I want to stress again that I understand that the schedule is tight, and there is a number of images to fix. As long as the group makes an informed decision to leave things as-is, having understood the mismatch: I am fine with this 😸

This is my mistake. It should really be fixed since it's the "anatomy of a CID" tutorial. The length should be 32 (00100000 in binary varint encoded form) instead of 128 and 2, as verified here:

(Note the first number, 18 is sha2-256)

alanshaw · 2020-02-27T23:22:41Z

FWIW IPLD formats are mentioned quite a bit in the specs and extensively in the current js-ipld API used by js-ipfs.

If these are not up to date and it's not a term being used anymore then please forgive me but I knew no better 🙏

zebateira · 2020-02-28T14:11:17Z

To sum up everything of the feedback:

Updating visuals
- representation of the hash in binary should be changed to represent 32 bytes (256bits) and we should mention the units always as well: either bytes and/or bits.
- updating bafy... highlight in the images to b...
- use codec as the multicodec indicator in the CID structure
Updating content
- representation of the hash in binary should be changed to represent 32 bytes (256bits) and we should mention the units always as well: either bytes and/or bits.
- use codec as the multicodec indicator in the CID structure
- shift the context of the tutorial from IPFS to Multiformats
- add summary suggested by Johnny

As mentioned by @ribasushi these edits can be fixed after we publish, which might not be a bad idea considering the length of this review and timeline for publishing this tutorial.

terichadbourne · 2020-02-28T15:08:48Z

The other missing piece in your list is some light reframing to fit the new Multiformats project label. I can take that on while you're out @zebateira.

@alanshaw are the "images" in your preso actually image files or are they Google Slides text boxes and arrows and such? Could I snag a copy of the original Google Slides file? Ze has been working from the PDF you shared in the camp repo.

Co-Authored-By: Johnny <9611008+johnnymatthews@users.noreply.github.com> Co-Authored-By: Peter Rabbitson <ribasushi@leporine.io>

terichadbourne · 2020-03-02T20:44:29Z

Latest commit updates images as follows based on recommendations from @ribasushi & @alanshaw. Please let me know if anything isn't as intended.

old

new

old

new

old

new

old

new

* feat: support projects * Feat/support multiple projects option 3 (#399) * fix: ui tweak option 1 * fix: ui tweak option 3 Co-authored-by: Zé Bateira <jlageb@gmail.com> * adjust project name placement Co-authored-by: Teri Chadbourne <terichadbourne@users.noreply.github.com>

terichadbourne · 2020-03-02T21:52:46Z

@mikeal I believe we've now made all the changes necessary to reframe this as a Multiformats tutorial. Would you have a sec to peruse as an end user (which will be much easier than reviewing the full code diff) and let me know if anything strikes you as incorrect or poorly explained?

ribasushi · 2020-03-02T21:56:17Z

@terichadbourne all the images in #359 (comment) are correct, thank you 🎉
Note that the images at #359 (comment) have the old (incorrect) 256-based value though.

terichadbourne · 2020-03-03T18:59:50Z

Shipping it! Please feel free to open issues for any suggested improvements moving forward.

Draft of the announcement blog post can be found here: ipfs-inactive/blog#379

- gateway redirects to a valid libp2p-key CID - CLI resolves as-is - style: use 'hostname' in places where host header may have explicit port License: MIT Signed-off-by: Marcin Rataj <lidel@lidel.org>

feat: add new tutorial - "Anatomy of a CID"

121ab14

zebateira requested a review from terichadbourne January 27, 2020 18:27

Small wording/formatting/typos/phrasing fixes for CID tutorial (#361)

be0fb78

zebateira self-assigned this Feb 3, 2020

terichadbourne mentioned this pull request Feb 4, 2020

Add link to new Anatomy of a CID tutorial in ProtoSchool multiformats/cid-utils-website#18

Closed

terichadbourne added 3 commits February 4, 2020 13:10

reference new tutorial from Decentralized Data Structures

525676a

fix caps in tutorial shortname

d798b2f

text edits for clarity/consistency

181175c

terichadbourne requested changes Feb 4, 2020

View reviewed changes

src/tutorials/0006/03.vue Outdated Show resolved Hide resolved

src/tutorials/0006/05.md Outdated Show resolved Hide resolved

terichadbourne requested a review from alanshaw February 4, 2020 18:38

terichadbourne and others added 2 commits February 4, 2020 14:11

text fix re encoding prefix

dec1b26

fix: more typos and grammar fixes

99c978d

zebateira mentioned this pull request Feb 5, 2020

Feature: Enable markdown on multiple-choice answer text #364

Closed

Ze Bateira added 2 commits February 5, 2020 17:18

fix: linting issues

f66bc20

fix: test if the we need the --disable-dev-shm-usage flag

bed6c4c

zebateira force-pushed the content/new-tutorial-anatomy-of-a-cid branch from 4b4c18d to bed6c4c Compare February 5, 2020 14:05

Ze Bateira and others added 2 commits February 6, 2020 14:59

fix: mention that it is not safe to guess the data encoding

c6830ed

Wording changes to resources list

5660f99

zebateira mentioned this pull request Feb 7, 2020

Bug: Resources page is only marked as completed if the user clicks on "More Tutorials" button at the bottom of the Resources Page #368

Closed

alanshaw suggested changes Feb 11, 2020

View reviewed changes

src/tutorials/0006/05.vue Outdated Show resolved Hide resolved

src/tutorials/0006/05.vue Outdated Show resolved Hide resolved

src/tutorials/0006/06.md Outdated Show resolved Hide resolved

Apply suggestions from code review

21f8879

Co-Authored-By: Alan Shaw <alan.shaw@protocol.ai>

fix: ipld-format -> ipld-codec

38878a5

terichadbourne and others added 2 commits February 27, 2020 11:41

resolve conflicts with code branch

9e4988e

Zé Bateira and others added 3 commits February 28, 2020 19:50

Apply suggestions from code review

97ca550

Co-Authored-By: Johnny <9611008+johnnymatthews@users.noreply.github.com> Co-Authored-By: Peter Rabbitson <ribasushi@leporine.io>

fix: refer to the multicodec prefix as codec only

5732910

replace images

6ff1f21

terichadbourne and others added 4 commits March 2, 2020 15:55

update descriptions of bits/bytes

1e2e642

adjust based on multiformats project designation

fc54ca7

update tutorial description for multiformats context

5be35da

terichadbourne added 3 commits March 3, 2020 10:01

fix bits/bytes reference

f4beece

image/typo fixes and wording tweaks

0ff983c

incorporate review feedback

9d1374e

terichadbourne closed this Mar 3, 2020

terichadbourne reopened this Mar 3, 2020

terichadbourne merged commit fc345c8 into code Mar 3, 2020

zebateira deleted the content/new-tutorial-anatomy-of-a-cid branch March 9, 2020 10:48

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add new tutorial - "Anatomy of a CID" #359

Add new tutorial - "Anatomy of a CID" #359

zebateira commented Jan 27, 2020 •

edited

Loading

carlbordum commented Jan 28, 2020

zebateira commented Jan 30, 2020 •

edited

Loading

carlbordum commented Jan 31, 2020

zebateira commented Jan 31, 2020

carlbordum commented Feb 1, 2020

zebateira commented Feb 3, 2020

terichadbourne left a comment

zebateira commented Feb 5, 2020 •

edited

Loading

terichadbourne commented Feb 12, 2020

terichadbourne commented Feb 27, 2020

zebateira commented Feb 27, 2020 •

edited

Loading

terichadbourne commented Feb 27, 2020

ribasushi commented Feb 27, 2020

alanshaw commented Feb 27, 2020

alanshaw commented Feb 27, 2020

zebateira commented Feb 28, 2020 •

edited by terichadbourne

Loading

terichadbourne commented Feb 28, 2020

terichadbourne commented Mar 2, 2020

terichadbourne commented Mar 2, 2020

ribasushi commented Mar 2, 2020

terichadbourne commented Mar 3, 2020

Add new tutorial - "Anatomy of a CID" #359

Add new tutorial - "Anatomy of a CID" #359

Conversation

zebateira commented Jan 27, 2020 • edited Loading

carlbordum commented Jan 28, 2020

zebateira commented Jan 30, 2020 • edited Loading

carlbordum commented Jan 31, 2020

zebateira commented Jan 31, 2020

carlbordum commented Feb 1, 2020

zebateira commented Feb 3, 2020

terichadbourne left a comment

Choose a reason for hiding this comment

zebateira commented Feb 5, 2020 • edited Loading

terichadbourne commented Feb 12, 2020

terichadbourne commented Feb 27, 2020

zebateira commented Feb 27, 2020 • edited Loading

terichadbourne commented Feb 27, 2020

ribasushi commented Feb 27, 2020

alanshaw commented Feb 27, 2020

alanshaw commented Feb 27, 2020

zebateira commented Feb 28, 2020 • edited by terichadbourne Loading

terichadbourne commented Feb 28, 2020

terichadbourne commented Mar 2, 2020

terichadbourne commented Mar 2, 2020

ribasushi commented Mar 2, 2020

terichadbourne commented Mar 3, 2020

zebateira commented Jan 27, 2020 •

edited

Loading

zebateira commented Jan 30, 2020 •

edited

Loading

zebateira commented Feb 5, 2020 •

edited

Loading

zebateira commented Feb 27, 2020 •

edited

Loading

zebateira commented Feb 28, 2020 •

edited by terichadbourne

Loading