Hacker News Reader

Comment by Mz | Hacker News Reader

helping with documentation + website

I am not a programmer. I do copywriting for pay and I have run a bunch of different personal websites over the years (15+ years, I think). I know a little HTML and CSS.

I am interested in getting involved in open source via first working on copywriting and website stuff, since that is what I already have a background in. I am finding it extremely opaque to figure out how on earth to do that.

I left a couple of related comments on HN recently:

https://news.ycombinator.com/item?id=12860294

https://news.ycombinator.com/item?id=12851361

I do have a github account and I recently went through the Hello World on how to do pull requests.

Any tips on how to begin interacting with open source projects on the copywriting and website development piece of things?

Thanks.

View on HN

I'd say broadly that the right first step is to communicate with the maintainers somehow. Figuring out how is part of it. Check for activity - how many PRs, open and closed, does the project have? How often do they come in, and how quickly do they get commented on or merged by project maintainers? Are they linked to Issues on GitHub or some other system, and what's the activity level on those? Maybe they have a mailing list, Google Groups, IRC, Slack, or something else. Find it, see if it looks active, maybe send out a quick hello and see if anybody responds, and have a chat with them about what you'd like to do, if they're open to that, and how they would like for you to proceed. If they use GitHub issues or some other open issue tracker, you could open an issue for poor documentation or whatever, with an offer to fix it, and see if anybody responds.

Sounds complex, but you should only spend like 10-20 minutes on this. If you can't find clear signs of activity in that amount of time, there's a good chance that the project is abandoned or only accepts contributions from a private group. It may take a couple of days or so to get a response to messages on less active projects, that's okay. If you can't see any activity or get any response from maintainers in a reasonable timeframe, then don't bother. If your contributions are wanted and have a good chance of being accepted into the project, then somebody should be willing to write a few sentences to you specifically telling you so, and outlining how to contribute or where to find a current contribution guide.

I think it depends on the project like mentioned.

For react, the docs for the website is in the same repo as the main code under "docs/" https://github.com/facebook/react/tree/master/docs.

A lot of projects do what we do with babel: have a separate repo with the whole username.github.io name: https://github.com/babel/babel.github.io.

And a lot of projects started adding links to edit the page you are currently on: http://babeljs.io/docs/learn-es2015/ (see the "edit this page" link on the header. For yarn it's on the bottom: https://yarnpkg.com/en/docs/. That at least makes it easy to edit a specific page for typos etc. Then you can just edit it from the website

That depends largely on what you want to edit. Websites might be static pages, generated from some simpler markup language or hosted on a form of CMS. Documentation is often generated from source code comments to some extent.

If you can't easily figure out where it is stored and how it is generated you should probably ask along with your inquiry whether the maintainers would be interested in contributions in that area.

Okay, so, you are suggesting I figure out who the project lead is and email them as my first step?

The preferred form of communication also depends on the project. Do they have an issue tracker? If so you could probably file one along the lines of "Page X could use some improvement" and ask whether they're interested and how it's done.

Some projects use mailing lists, forums or even irc.

Open, group-based forms of communication are usually preferred because it allows anyone qualified to respond instead of pinning it on a particular person.

Thank you. This helps. I get told all the time "Just do X!" and then I try X and it blows up in my face because it turns out you only do X under (long list of conditions that no one ever told me and assumed I knew).

One thing I forgot to mention, this also depends on project size.

Larger projects, especially corporate- or foundation-backed ones, might have less-technical staff dedicated to the web presence/PR/outreach etc. which might use other communication channels than the developers.

> Then I try X and it blows up in my face because it turns out you only do X under (long list of conditions that no one ever told me and assumed I knew).

You don't necessarily have to know. Some exploration and just asking for pointers is often required.

I get anxious about this too sometimes, but in my experience the "long lists of conditions that no one ever told me and assumed I knew" are hardly ever relevant.

I don't get anxious. I get tired of doing what people told me would work and having it go really badly.

Complaining about freely volunteered advice people give you in a friendly and helpful spirit is a good way to avoid getting it.

Well, that isn't what I was doing. Since you are not among those being actually helpful to me in this discussion, you are more than welcome to stay out of it if you feel that some remark of mine somehow constitutes bad behavior. I have upvoted every single reply that was useful to me and said thanks twice.

What were you doing? If someone volunteers advice, just be appreciative and try it if you want. Don't slag them off if it doesn't work out for you. It's not their fault they don't understand everything about what you need to do to implement their advice.

Reply on news.ycombinator.com