Skip to content

Conversation

@michaelfolkson
Copy link

I think I have followed all your instructions David with three deliberate exceptions. Please let me know if I have made any errors and I will push changes asap. I am sure there will be some formatting changes required which I will make sure I follow for next month's.

I have deliberately started each transcript section with the name of the individual doing the presentation. Personally I think this is the most important piece of information for readers of the newsletter. Adam Back doing a presentation on Simplicity is much more of interest than say myself (e.g. significantly less Simplicity expertise) doing a presentation on Simplicity.

I haven't linked to the videos or slides in the newsletter because this is the transcript section rather than the video section. But in all cases the link to the video and slides are in the transcript so it is easily found. I think having less links makes the presentation in the newsletter less crowded.

I have included an "transcript from the archives." I really like this idea as there are some really informative transcripts on all kinds of topics from the past. These tend to get forgotten about as people are attracted to new and shiny and things. Having this feature will be useful to resurface relevant past transcripts when past challenges and discussions repeat themselves. There may be a better transcript than the one I have chosen this month but hopefully you agree this is a good feature.

If you disagree with any of the above please let me know. Obviously if I can't convince you on any of the above feel free to overrule. Hopefully my rationale is somewhat convincing.

Copy link
Owner

@harding harding left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is good! Thank you. I've left a couple comments on the content below and I'll leave a separate comment with some higher-level feedback. I plan to merge this into the main PR later this (Sunday) afternoon so that other people can comment on it. Feel free to make or not make any of the changes suggested below before then; I'll make any remaining changes I think are necessary after the merge.

@harding
Copy link
Owner

harding commented May 3, 2020

Some suggestions:

  1. I suggest that we use a list rather than a series of paragraphs. Although I admit lists are a bit boring given that the other sections of our newsletter are also all lists, it makes it very easy for readers to skim the newsletter---specifically, to move from an item they're not interested in to the next item. With a series of paragraphs, you never know if the next paragraph is a continuation of the topic from the previous paragraph or a completely new subject.

  2. Although starting with names is logical (since every transcript will have a speaker) and useful (as you note), a key reason I suggested that each item start with a link to a title of the transcript is that we have auto-formatting magic on the website with will turn list items starting with a link, bold, or italics into HTML anchors that can be linked to by later newsletters, other pages on our site, and other websites. I don't think we should start items with someone's name and a link (that seems like google bombing), but I think it's just as easier for readers to skim by name relevance if we always put the name after the title of the talk, e.g.:

  3. Re: "I haven't linked to the videos or slides in the newsletter because this is the transcript section rather than the video section. But in all cases the link to the video and slides are in the transcript so it is easily found." There are three reasons I suggest linking sources:

    1. It makes readers aware the sources exist. When Bryan is live-transcribing, there often aren't any sources (though sometimes they become available later). Additionally, what sources are available often varies by talk---for some talks, it might be just audio or video; for others, there are slides; for others, there's a paper or other document we can also link to (e.g. LND release notes for roasbeef/joost/gugger's talk or Kalle's website for his book). Giving readers a link in the summary makes them aware those resources are available even if they don't decide to read the transcript.

    2. Linking to the sources improves the pagerank for those sources. If something is good enough for you or Bryan or some other contributor to spend time transcribing, I think it's something we want to rank well in search engines. Since Optech is itself a high-ranking website within the Bitcoin niche, our links count for more than most, so I encourage using that power for good.

    3. If I were a reader, I'd rather have links to the source material linked and so the golden rule says I should add those links if they aren't too much bother.

  4. Re: "transcripts from the archive": I completely agree that too many people are focused on the latest thing and there's a lot of great old content going unused. (I am perhaps especially aware of that given the amount of old, unused, but still basically useful content that I've written myself.) However, I personally feel that a newsletter should be focused on what's new. I suggest (but I don't require) to drop the archive transcript for this month and we can look for some other way to resurface great historical content (maybe outside of the newsletter or outside of Optech altogether).

The remainder of my comments relate to style and formatting. None of them are important to make this month (or I'll make the changes myself).

  • If possible, wrap lines at approximately 72 characters. This makes it easier to leave PR review comments on a particular bit of text rather than leaving a comment on the whole paragraph. It also often makes it easier to compare diffs to see what's changed.

  • Only use reference-style markdown links, (e.g. [link title][optional reference name]) with all reference definitions going in the bottom of the page. This makes the text more readable, easier to spell check, and simplifies automatically stripping the link references from the text using non-markdown-aware tools (e.g. grep and sed).

  • Optech's policy is that the primary author of a document gets to define its basic style (e.g. American vs British spellings, etc.). For the newsletters, that means my style, so my two nits related to your text are:

    1. Use the serial comma (a, b, and c; not a, b and c)
    2. Refer to persons by their surname ("Osuntokun presented a new [...]" not "Laolu presented a new [...]")

Sorry for such a giant post, please don't be disheartened---if I didn't like what you've written, I wouldn't be commenting on it at length. Thanks again!

@michaelfolkson
Copy link
Author

Thanks for explaining all this context David. All makes sense to me. I will try to make some of these changes later today but I am busy for the next 3-4 hours. If I don't get it to you before you start working on it obviously no need to wait.

@michaelfolkson
Copy link
Author

Made the majority of the changes requested. As said earlier, any formatting changes that you still need to make I will follow in next month's.

@harding harding merged commit b856ddf into harding:2020-05-06-newsletter May 4, 2020
@harding
Copy link
Owner

harding commented May 4, 2020

Thanks!

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants