Start contributing a Q&A and Glossary

[henkvancann]

I have trouble unifying the "docs" and "Docs" subdirectories remotely on GitHub. Locally on my computer is it says:

hvc@Henks-Mbp20 GordianSeedTool-iOS % mv ./docs/* ./Docs
mv: ./docs/Glossary.md and ./Docs/Glossary.md are identical
mv: ./docs/MANUAL.md and ./Docs/MANUAL.md are identical
mv: ./docs/Q-and-A.md and ./Docs/Q-and-A.md are identical
hvc@Henks-Mbp20 GordianSeedTool-iOS % git push origin
Everything up-to-date
hvc@Henks-Mbp20 GordianSeedTool-iOS %

Any ideas welcome how to solve this uppercase / lowercase thingy.

[wolfmcnally]

I've asked @shannona to look this over, as he's primarily responsible for SeedTool's documentation.

[henkvancann]

I've asked @shannona to look this over, as he's primarily responsible for SeedTool's documentation.

Hi Wolff, I asked Shannon beforehand for assistance :)

[shannona]

Hey, Henk. I looked through the Definitions and Q&A this morning, and generally think it's good and very usable. I only have one workday scheduled for Blockchain Commons before the end of the year, so I may not be able to do a full edit before then, but if not it'll be near the top of my list for the new year.

General comments:

• Definitions. Looks great. As I told you, this type of thing can be problematic as there's a lot of disagreement in the space about what means what to who, but you're going for the big picture stuff most directly touching Seed Tool, and backing it up with references helps a lot.
• Q&A. These also look like good questions and answers, my main notes are stylistic:

• I'd suggest not leaving in quotes/references from other people (e.g., Wolf, Chris). Just incorporate it into the overall Answer if possible.
• I assume the shorthand [x] references mark Issues that you're replying to. The concept is great, but I'd deemphasize and clarify the reference. Like maybe saying at the end of the answer: In reference to Issue #XX. And I'm hopefully that'll link to the issue too, making it easy to close if it's not already.
• The organization feels a little scattered to me, just in what should go in what section. I'd think about other ways it can be organized. Maybe look at the Manual (https://github.com/BlockchainCommons/GordianSeedTool-iOS/blob/master/Docs/MANUAL.md) for one organization of major topics, though clearly that won't cover some of the more general questions like the relationship of SSKR and Shamir's Secret Sharing, and it's not necessarily right for this, just a thought. It could just be that this requires a second set of eyes less close to the original Q&A, in which case I'm happy to do it.

Overall, looks like a strong start and some beneficial docs for the repo. I'm happy to do a next editorial pass when your draft is done, so let me know, though as I said it may push into next year depending on the priorities & time I have on Tuesday.

[henkvancann]

Hi Shanon, Thx for your help. See my response inline between [ ] Best, Henk

On 16 Dec 2021, at 20:47, Shannon Appelcline ***@***.***> wrote: Hey, Henk. I looked through the Definitions and Q&A this morning, and generally think it's good and very usable. I only have one workday scheduled for Blockchain Commons before the end of the year, so I may not be able to do a full edit before then, but if not it'll be near the top of my list for the new year. General comments: Definitions. Looks great. As I told you, this type of thing can be problematic as there's a lot of disagreement in the space about what means what to who, but you're going for the big picture stuff most directly touching Seed Tool, and backing it up with references helps a lot.

[At BCC we should be happy with the defs I choose or cite. Because I’ve phrased the condition of use at the beginning: only in the context of Gordian Seed Tool. For beginners a list of definitions is indispensable, I think.]

Q&A. These also look like good questions and answers, my main notes are stylistic: I'd suggest not leaving in quotes/references from other people (e.g., Wolf, Chris). Just incorporate it into the overall Answer if possible.

[Will do]

I assume the shorthand [x] references mark Issues that you're replying to. The concept is great, but I'd deemphasize and clarify the reference. Like maybe saying at the end of the answer: In reference to Issue #XX. And I'm hopefully that'll link to the issue too, making it easy to close if it's not already.

[The [x] should go, they are a copy paste error. I will leave the move the references to the end.

The organization feels a little scattered to me, just in what should go in what section. I'd think about other ways it can be organized. Maybe look at the Manual (https://github.com/BlockchainCommons/GordianSeedTool-iOS/blob/master/Docs/MANUAL.md <https://github.com/BlockchainCommons/GordianSeedTool-iOS/blob/master/Docs/MANUAL.md>) for one organization of major topics, though clearly that won't cover some of the more general questions like the relationship of SSKR and Shamir's Secret Sharing, and it's not necessarily right for this, just a thought. It could just be that this requires a second set of eyes less close to the original Q&A, in which case I'm happy to do it.

[Yes, I just started off with an organisation of categories, and will invent a more suitable one, at the end of the effort.]

…

Overall, looks like a strong start and some beneficial docs for the repo. I'm happy to do a next editorial pass when your draft is done, so let me know, though as I said it may push into next year depending on the priorities & time I have on Tuesday. — Reply to this email directly, view it on GitHub <#106 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AADVA7GTL2JJWLHQ724DREDURI643ANCNFSM5KETAWJQ>. You are receiving this because you authored the thread.

[shannona]

I did a line edit of both the Glossary and the Q&A. It might need some additional polish down the road, to bring it into full sync with the manual and other docs, but I think it's a value-add and would suggest merging at this point.

[shannona]

(Thanks Henk!)

[ChristopherA]

@wolfmcnally will you merge this if it is ok?