search

sourcegraph / sourcegraph-public-snapshot

Code AI platform with Code Search & Cody
https://sourcegraph.com
Other
10.11k stars 1.27k forks source link

API docs: project overview & weekly status updates #19905

Open slimsag opened 3 years ago

slimsag commented 3 years ago

In this issue I will summarize my work weekly on API docs.

Product Design, RFCs, and other public memos (most recent last)

slimsag commented 3 years ago

Week of Mar 26, 2021

I have a document detailing our data requirements from LSIF, exploring how LSIF/LSP meets that today, and discussing some LSIF/LSP extensions I plan to propose in the future: https://docs.google.com/document/d/1NcNYXOnprknfHkSTMOh1ST8een-NQUVuWCg5DbMmksM/edit?usp=sharing

I have a much clearer picture today about what we need to get to a usable Go MVP today (mostly Go indexer work, no new LSIF extensions) than I did e.g. even yesterday.

I have pushed various stakeholders to commit to specific high-level goals, and have gotten much clearer direction on that and general agreement on the implementation plan, etc.

slimsag commented 3 years ago

Week of Apr 2, 2021

This was a short week due to me being out a day for my vaccine, plus 20% of my time going towards some unexpected customer incidents and helping others internally.

I discussed with Jean and Malo requirements from Nick, and got agreement on why focusing on search right off the bat (before hitting the MVP) would not make sense. In response to all of this, I have put together and initial "User problem" that we are solving, and worked with Jean and Malo to refine it. - you can find it in the implementation plan

2d was spent looking into lsif-go; I merged my first PR there and learned about how the codeintel test suite works. I continue to work on https://github.com/sourcegraph/sourcegraph/issues/19591 and am not blocked on anything.

slimsag commented 3 years ago

Week of Apr 9, 2021

Also a short week due to Easter holiday (out Mon & Tue.)

I made good progress on lsif-go support for textDocument/documentSymbols. I ran into a really nasty issue and burned a full day debugging what was going on, and am still waiting on Eric to get confidence I'm right about the cause (https://github.com/sourcegraph/lsif-go/pull/142) before I merge a fix. There was a lot of time spent making sure that how I build this out will accommodate the future LSIF expansions we'll need, and that I'm faithfully following the LSIF/LSP spec (which is super underspecified in general, and was implemented incorrectly in Beyang's original PR.)

I am about 2-3 work days away from finishing the lsif-go work, at which point I will be onto the next challenge: getting Sourcegraph to store that data https://github.com/sourcegraph/sourcegraph/issues/19592 and enabling us to query it https://github.com/sourcegraph/sourcegraph/issues/19593 - it's unclear yet how long those issues will take, but I'm optimistic generally and believe we're only a few weeks away from breaking ground on the actual webapp frontend for this.

Unrelated to API docs, I helped resolve an ops issue (segfault) with Cloud SQL, discussed some customer support things and other random stuff in about 15% of my time.

slimsag commented 3 years ago

Week of Apr 16, 2021

Lots has been learned this week, and I finally feel like we're on a clear path to having the data we need from LSIF.

Early this week, and after several conversations with codeintel team, it became clear that my current approach of using a handful of existing LSP methods to build out API docs would not suit us well in the long run. In light of that, I pivoted the direction to using a custom LSIF/LSP extension for API docs.

This new direction will better serve us long-term, ensure we aren't wasting our time building the MVP only to find we need to redo a lot of stuff to win the hearts and minds of Go/etc developers when we want to get into the more advanced functionality. It better enables us to support advanced functionality, makes it easier to parallelize work on multiple languages if we want to, and is generally a Whole Lot Better™. It doesn't materially impact our timeline, because I knew something like this would happen and planned ahead so we had the needed time to get this right.

Working in that direction:

I believe we're 1 week away from working on LSIF storage aspects, and 2-3 weeks away from breaking ground on the webapp frontend.

Additionally:

slimsag commented 3 years ago

Week of Apr 23, 2021

API docs

By my count, I should have been done with the lsif-go indexer implementation last Friday. That didn't happen, and I consider us behind-schedule by approx. 4 days.

I still have confidence in hitting our May 19th "Go barebones/internal implementation" target.

Outside API docs

slimsag commented 3 years ago

The last two weeks I have been on a "focus vacation", as I described in Slack:

I will be trying an experiment I'm calling a "focus vacation" over the next two weeks.

What is it?

The idea is that Slack conversations, meetings, interviews, etc. take up "only ~20% of my time" but can be very disruptive to my focus, often coming up at the worst of times - and regardless of me scheduling "focus time" blocks on my calendar I interrupt myself. I will be taking a 2 week "working vacation" where I will be focusing really heads-down on coding API docs in a hyper-focused/hyper-productive state, since I typically find when I am away from Slack/meetings for extended periods my motivation and drive goes up substantially.

Here's how it will look:

  • I will be in offline-mode starting tomorrow, until May 14th (2 weeks, back in time to help onboard Coury for code insights)
  • I will update my calendar and Slack statuses to reflect I am on a "vacation" to avoid interrupts
  • I will still be keeping general tabs on things: watching company meeting recordings, checking Slack occasionally just for really urgent things I might need to be aware of, to direct people to someone else, etc.
  • You'll still find me regularly submitting PRs, chatting with others to push my PRs along. I may decide to post an update if something really cool happens, otherwise you'll get one "big" update at the end. :slightly_smiling_face: The goal here is to be hyper-focused and more productive than usual.
  • I won't be attending any meetings during this time, and will ask e.g. the hiring team to swap me with others such as for interviewing the "Director of Product - Global Code Graph" candidates.

This is an experiment, I have some strong evidence this will be helpful (especially at this point in API docs' history where the planning dust has settled and all that is left is for me to "implement it") - this post is for me to refer others to in case they are interested in this idea themselves or have questions :slightly_smiling_face:

How it went

Overall, it went really well! I was able to really go heads-down and just focus on the code, which helped me make a ton of progress.

One thing that really helped here was that if I was "in the zone", I was able to just continue. I didn't need to account for the next meeting I had scheduled, pan to wake up at a reasonable time the next morning, get interrupted by helping someone over Slack, etc.

It also didn't feel like overwork to me, it felt like a nice break from my regular day-to-day. There were some days I didn't feel very productive, so I just stepped away entirely for that day. I was only able to do that because I didn't have meetings, the expectation of being on Slack, etc.

I am going to wait to share a more specific update about the progress I've made on API docs from a technical POV, but we may well be ahead of schedule a bit thanks to this.

slimsag commented 3 years ago

Week of Apr 30, 2021 (past)

image
slimsag commented 3 years ago

Week of May 21, 2021

image
slimsag commented 3 years ago

Week of June 12

Back from a (real) two week vacation.

slimsag commented 3 years ago

Week of June 18

This week, I started out quite focused on our goal of making API docs public (no feature flag) ASAP. A lot of progress has been made, and I think we can have this finished next week.

I want to stress that because of the way LSIF works, if we want to expand/alter our generated data format to support more features in the future (whether that be search integration, jumping from API docs <-> code, or something else) we'll need to either maintain backwards compatibility for the old and new format while it rolls out (complex and time consuming) or wipe all data and start from scratch (losing all docs pages we currently have indexed, and potentially getting severely ding'd by Google.)

Because of that, I took this week to solidify the data format as much as possible. This will make it easier to roll out the features we think we want in the future (search integration, API docs <-> tooltip integration, etc.) with less risk of getting slowed down by having to deal with old and new data formats.

In practice, this means I've fixed a lot of issues but none of them have rolled out yet. Next week, all data will be wiped and we'll start fresh and begin public indexing by Google.

What's happened behind the scenes?

Lots of smaller bug fixes:

slimsag commented 3 years ago

Week of June 25, July 2

Outside API docs

API docs

See CHANGELOG: https://github.com/sourcegraph/sourcegraph/blob/main/CHANGELOG.md#api-docs-experimental

video: https://drive.google.com/file/d/126LLrQanXH7rHr0d8d_qvmnSpdefBa2V/view?usp=sharing

image
slimsag commented 3 years ago

Key highlights recently for posterity:

Notable mentions outside of API docs:

slimsag commented 2 years ago

recap

Aug 23rd

I am beginning work on sitemap generation for Sourcegraph.com - sharing my approach in case anyone has feedback.

You can now link to individual symbols and types and get a single-page sharable link in API docs. For example:

For structs/interface types, the page will include all the methods, constructors, etc. below the type so you can see that whole type's API. For variables/constants, it's just that on its own. Then you can click the ← View all of package tar or anywhere in the sidebar to super quickly navigate back to the full package view.

Aug 24th

Running some numbers on what we have indexed with API docs so far:

1 million fairly high quality pages; should be a great start for our SEO effort I think.

Aug 26th

Sept 1st

OpenGraph metadata changes went live

image

Sept 2nd

We hit 600-700 MAUs

image

Sept 6th

Major improvements to our SEO metadata for API docs in specific:

image

Sept 8th

New direction

I now have the question "where best to spend my time?" At this point, I see our biggest risks as:

I therefor think my time is best spent trying to de-risk those possibilities. The two next-best opportunities I see here are:

I will begin experimenting with these and monitoring the Google situation.

Quinn agrees with editor integration; Jean agrees with both.

Sept 9th

Quinn Keast holds a demo day video talk about our work collaborating on the design of API docs UX.

Sept 13th

Little #cloud-growth update: Google has indexed 15,000 API docs pages and continues to index at around 1.8k pages/day. Some (very) choice picks of google searches that turn up useful results:

It'll likely be a few months before this will really start turning up good results in general: Google's indexing is quite slow and I've submitted half a million pages for indexing, and asked it to remove several hundred thousand garbage pages so it'll be a while before it all propagates. More soon!

We've received feedback from ~10 internal developers.

Sept 23rd

Sept 27th

API docs SEO update

Sept 30th

Oct 6th

Oct 7th - Key milestone: 2k MAUs

image