Should we have someone own docs full time?

[Lior539]

Should we have someone own docs full time?

Motivation:

• "Docs that spark joy" is a theme that occurs every few quarters (I did whole bunch of docs work in Q3 last year, we're doing it again this quarter)
• We get feedback on the docs in this channel constantly, but no one owns it and a result its not always actioned I think Me and Ian sometimes action it, but I tend to forget about it /intentionally not prioritize

Should we hire someone?

• I think at this point owning the docs can be a full time job. I dont think myself or Ian are particularly excited about it though.
• We already have strong opinions on what our docs should be + we've done the job ourselves, so fits nicely into our philosophy of "do the job yourself first before hiring someone"
• If we do hire someone, we need to develop a strong vision for what we'd like our roadmap to be first, so that we can set them up for success

[Lior539]

tagging relevant folks for comment: @charlescook-ph @andyvan-ph @ivanagas @jamesefhawkins @corywatilo @jtemperton

[charlescook-ph]

Would we consider establishing a relationship with a good contractor for this kind of thing? ie. continue doing what we're doing in terms of rotating a bit of responsibility among the team, but periodically get someone in for a 1 or 3 month burst of focused activity if there is some big piece of work we want to do?

(Not 100% sure today it would be the next marketing hire we'd make, but I could see it in the future.)

For context, do we have a list somewhere of all the docs work we'd like to get done that we're not getting to?

[Lior539]

There are three parts to this:

1. Keeping existing docs up to date
2. Addressing feedback from users
3. Up-leveling our docs

Currently, we focus only 1) every few quarters, and sometimes 2 (although not consistently).

If we hire a contractor, they could 1 mostly, and perhaps also some of 2. A full-time employee could focus on all 3.

[ivanagas]

Based on the work we are doing now, I don't think it is enough for a full time person. If we look at how much time we spent on it over the last two years, it is like 1 person equivalent this quarter and 1 person equivalent in 1 quarter of 2023, but the rest of the year it is much less than that.

Beyond the work that we are planning to do, the benefits would diminish significantly. There are many docs we are updating now that have never been updated, but once updated, they will remain up-to-date for a long time. For example, a lot of the product analytics docs remained unchanged for 2 years with no big issues.

Based on my research, our docs are in a pretty good place. API docs could be improved a lot (which is more a technical problem), but beyond that, there is no big gaps as far as I can tell. Core information is clear, most complaints are minor points or account-specific issues.

Docs updates is very reactive to product teams. Some teams do a good job at writing first drafts which is often enough for us to work on to keep things updated. I also think we do a fine enough job at addressing feedback. Someone focused on this would do a lot of waiting around.

I also don't think a contractor would have enough context to do well. For example, updating and upgrading HogQL docs requires a lot of specific knowledge about PostHog. I would much rather someone working on video (which could be videos for docs) or community/influencers/events first before a docs person.

[andyvan-ph]

I think docs needs a proper owner, but I'm unconvinced this is a whole job.

@joethreepwood has stronger opinions on this than me, but I feel like this ought to be part a dev rel/dev advocate type role – i.e. someone who also leads on the community side, is responsible for ensuring developers have a great experience using PostHog, which would include pastoral care and ownership of the docs.

Thinking out loud, problems I think we need to solve:

• Working with influencers: Ian has done great work here, but it needs more time than he has to take it to the next level. I think we've proved it works.

• Community engagement: Making sure free and open source users have a great PostHog experience, and that they're engaged with helping each other + not reliant so much on us for support. TL;DR: Actively working to make our community aspirations real.

• Docs: Someone who owns the docs and works to constantly improve them in partnership with the content and product teams. This would fall under "developer experience" for me.

I think these are all problems that a Dev Advocate / Dev Rel role could own and solve.

[charlescook-ph]

@andyvan-ph do you want to have a go at filling out a role request template for this one?

One thing - I think it would be a shame if hiring someone to 'do' community and docs basically means that as an organization we drift into everyone else not caring about that stuff because now we have a person to do it (which I can definitely see happening).

Also worth tagging @jamesefhawkins and @corywatilo in it given the community overlap.

This is probably more a 'Technical Community Manager' or similar - devrel/advocate type people tend to want to spend lots of time attending/speaking at conferences and doing more brand building-y stuff, whereas really the influencer stuff is more like classic marketing project managementy work (ie. a lot of grunt work briefing, chasing, reviewing etc.).

[joethreepwood]

I do have strong opinions on this, as Andy said. Short version is I think there are two ways to tackle this:

1. We staff up support engineers and make docs a support engineer responsibility.
2. This is a community-focused role as others have said.

My strong preference is 2. Support won't scale.

I pretty strongly agree with Charles that this should not be a Dev Rel/Adv role, for the reasons Charles says. I think we should be looking for someone with explicit experience in either/both Technical Writing (e.g. writing docs specifically) and Community Management. Someone who has in-roads or experience with influencers would be a plus.

I do think this could be a full time job, as there's a lot to be done beyond simply updating the docs content to a point of completeness.

[charlescook-ph]

@joethreepwood maybe you are better placed to write something up here? (Seems like you've thought about this the most out of everyone.)

We can then riff on the specifics of the role a bit there, but I think we're all broadly in agreement that a new role in this area would be a good thing.

(Obv not promising we will hire or when, but it's easier to say yes when we have a more fleshed out spec for what we need the person to do! 😄)

[joethreepwood]

Thoughts welcome https://github.com/PostHog/company-internal/issues/1391