Add a GitHub Case Study Write-Up #38
Conversation
Deploying with
|
| Latest commit: |
5e55bb1
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://c19583a5.blog-cie.pages.dev |
| Branch Preview URL: | https://gh.blog-cie.pages.dev |
Still a few more details to add in.
| * that YAML or JSON data files which contain page content and which have been hand authored by content writers are correctly formed | ||
| * that the context object created at runtime which contains the entirety of the site content along with a site tree for the application is itself correctly formed | ||
|
|
||
| <p className="text-2xl my-10">"Choosing JSON schema to allow JSON schema validation was a natural and obvious choice that our team made. It has been a fundamental part of our application since we moved from having a static site to a dynamic application about 3 years ago." - Rachael Sewell & Robert Sese, Docs Engineers at GitHub</p> |
There was a problem hiding this comment.
The doc didn't attribute its contents to either of the team members at GitHub -- not sure if you know who the voice of the document is. For now I attributed the quote(s) to both of them, though I guess we can also possibly ping them to kindly review the post itself at some point if we want and if they care to.
There was a problem hiding this comment.
Yes, we will do that for sure.
pages/posts/github-case-study.md
Outdated
| title: "How JSON Schema Was an Obvious Choice at GitHub" | ||
| date: 2023-07-31 | ||
| type: Case Study | ||
| cover: /img/posts/2023/github-case-study/github-mark.svg |
There was a problem hiding this comment.
This SVG needs shrinking probably, I guess to some extent it too was a placeholder.
There was a problem hiding this comment.
Prefer webp. You can download the cli converter from here: https://developers.google.com/speed/webp
Yeah, I think it is a placeholder. Will need something else.
There was a problem hiding this comment.
Surely webp is preferred over png/jpg/etc. but not for svg? Though if/when we have an idea for a replacement probably it won't matter.
There was a problem hiding this comment.
You know, I missed that it was svg.
But anwyay, I expect it will be replaced. I... didn't realise what it was when I made that comment anyway.
There was a problem hiding this comment.
Looks like a great start! Thanks!
I feel that some of the content goes into too much depth, but I don't know if my target readership is right either.
My preference would be to convert the technical detail into business value, which speaks to both developers and non-developers.
Of course, shout when you've made revisions and added that last section as you mentioned.
Then I'll reach out to the people at GitHub for commnet and review.
🙌
|
Cool! Thanks for the review -- I actually added that section (it was the solution section) so will take out of draft, but will take another look anyhow now that you left some comments to see if there's anything else in the document that can be added!
Yeah not sure either, certainly the opinion is welcome. I'm very much personally not a fan of overspeaking business value when it's not clear there's good evidence for it, and for me the bar is very high there to me, so simply stating facts is always my preference unless there's specific evidence to speak of (e.g. "I did X and it made my machines faster and so I saved $Y" which is generally incontrovertible). I know others have different opinions certainly, so I'm clearly happy if we decide to go for more there, though I'm not sure how much more was in the source doc, will have another look. |
Oh for sure. I only use what is provided. No making up or exaggerating things here. |
There was a problem hiding this comment.
This looks wonderful! Thank you so much for the write up. I'm not sure that it's valuable, but the code used to power docs.github.com is fully open-source at https://github.com/github/docs. If folks want to poke around source code, it's all there including the content.
I'm working on getting the images from our marketing department. I can link those up here when I receive them.
Co-authored-by: Rachael Sewell <[email protected]>
|
@Relequestual I uploaded 3 images that were approved for use in the blog post to the Google drive you set up: |
Remove unused heading.
|
I've added the images. So, if you want to preview with the images in place, I can make a screenshot, or you can clone it and run it locally. @rachmari I think we are just waiting on your approval now. I don't know if we want to coordinate publication with anything on the GitHub side like social media postings. (cc @benjagm) |
The last person that needs to approve this is @mollyryner. I'll defer to Molly on whether we should time this with any GitHub-related posts. |
pages/posts/github-case-study.md
Outdated
|
|
||
| <p className="text-2xl my-10">GitHub is the world's largest developer platform, helping developers and organizations around the world to build, scale and deliver secure software.</p> | ||
|
|
||
| Founded in 2008, GitHub's $7.5 billion acquisition by Microsoft was finalized in 2018, and the company has only continued to grow since, currently with approximately 2,000 employees worldwide. |
|
Thanks, I reviewed and left one comment. No need to coordinate with anything on our end. Once it goes live, we'll share with our social team for amplification. |
|
Hooray, thanks all!! Exciting stuff. |
This is waiting for a last section to be plopped in (which I'm porting from the case study document)EDIT: it's in, and then also needs a second look-over (and of course a review from others with any comments).But putting it up now, will continue to tweak, but feel free to chime in with comments!
(The title is/was also a placeholder, not sold on it as-is)