Unemployed technical writer seeks open source project in need.
January 28, 2014 8:53 PM Subscribe
Which open source products do you use that have lousy documentation?
I'm a technical writer who got downsized in November. I have a long-ish career, a lot of experience, but not much of a portfolio because I can't share a lot of my work due to NDAs. I want to take on a side project that will help out an open source project in need while building a stronger portfolio at the same time.
So, which open source products do you use that could stand help in the areas of user/admin guides, tutorials, reference material, etc.?
Alternatively, are you aware of a resource where open source projects post calls for help based on need? (I've hunted around a bit, but came up empty.)
I'm a technical writer who got downsized in November. I have a long-ish career, a lot of experience, but not much of a portfolio because I can't share a lot of my work due to NDAs. I want to take on a side project that will help out an open source project in need while building a stronger portfolio at the same time.
So, which open source products do you use that could stand help in the areas of user/admin guides, tutorials, reference material, etc.?
Alternatively, are you aware of a resource where open source projects post calls for help based on need? (I've hunted around a bit, but came up empty.)
Boost. Especially it's bjam build system.
posted by tylerkaraszewski at 9:14 PM on January 28, 2014
posted by tylerkaraszewski at 9:14 PM on January 28, 2014
I would try looking on OpenHatch!
As a developer, one thing that is really lacking for me is the documentation for Django's class based views. I would hope they'd be receptive to somebody coming in and really revamping it.
I work with a project called Dreamwidth (which is social blogging software) where I admin the wiki which could always use loads of work. There are bugs open for documentation on the commercial operating site side (warning: might need an account to view, but not because anything is sensitive) as well.
posted by foxfirefey at 9:21 PM on January 28, 2014
As a developer, one thing that is really lacking for me is the documentation for Django's class based views. I would hope they'd be receptive to somebody coming in and really revamping it.
I work with a project called Dreamwidth (which is social blogging software) where I admin the wiki which could always use loads of work. There are bugs open for documentation on the commercial operating site side (warning: might need an account to view, but not because anything is sensitive) as well.
posted by foxfirefey at 9:21 PM on January 28, 2014
Interested in doing an open source hardware piece? I run a project that gets pretty wide exposure and could use some help.
posted by fake at 9:57 PM on January 28, 2014
posted by fake at 9:57 PM on January 28, 2014
Response by poster: Interested in doing an open source hardware piece?
Sure - I'd be open to hardware too. I worked a short contract at Intel years ago, but aside from that I don't have any hardware experience. And I'm not sure the Intel job fully qualified as "hardware experience"... it was extremely hands-off and more "just format these engineering docs to comply with standards". No opportunity to learn anything aside from the Intel Style Guide.
(Thanks for the all the suggestions so far.)
posted by 27 at 10:24 PM on January 28, 2014
Sure - I'd be open to hardware too. I worked a short contract at Intel years ago, but aside from that I don't have any hardware experience. And I'm not sure the Intel job fully qualified as "hardware experience"... it was extremely hands-off and more "just format these engineering docs to comply with standards". No opportunity to learn anything aside from the Intel Style Guide.
(Thanks for the all the suggestions so far.)
posted by 27 at 10:24 PM on January 28, 2014
I've done some technical writing and editing for DreamWidth a few years ago.
posted by spinifex23 at 11:48 PM on January 28, 2014
posted by spinifex23 at 11:48 PM on January 28, 2014
VideoLAN, Audacity, Calibre, and GIMP all have quite a bit of documentation, but they are all quite active projects, so there may be opportunities for contribution.
posted by neushoorn at 11:59 PM on January 28, 2014
posted by neushoorn at 11:59 PM on January 28, 2014
DD-WRT is used by a lot of consumers, and its documentation and help absolutely suck. A basic set of how-to/tutorial/troubleshooting guides for common use cases would be a godsend, even though (as always) the usability problems really run deeper than just documentation.
posted by RogerB at 12:01 AM on January 29, 2014 [2 favorites]
posted by RogerB at 12:01 AM on January 29, 2014 [2 favorites]
Almost all open source projects need help with documentation. There are so many that I'd suggest choosing a project based on your interests/specialties and what would impress your potential clients — and potentially one that would help you make connections to get new clients.
It's also important to find a project that doesn't just need help, but also has a decent process for accepting help. Bigger projects tend to have some kind of documentation and infrastructure for assisting new contributors - a mailing list, IRC channel, or other forum where you can find existing contributors and ask them for advice on what projects to tackle. For example, MediaWiki, Mozilla, and LibreOffice are name-brand projects that would probably look nice on a resume and also have some explanation of how to contribute documentation.
And yeah, OpenHatch's database might be the closest thing available for a database of projects asking for help - it encourages projects to list themselves, and it indexes their "bite sized" bugs that are good for new contributors. You can start on the OpenHatch search page, click "documentation", and see if any of those bite-sized documentation tasks looks fun to try. (And I volunteer my own skills helping OpenHatch, yay!)
posted by dreamyshade at 12:53 AM on January 29, 2014 [7 favorites]
It's also important to find a project that doesn't just need help, but also has a decent process for accepting help. Bigger projects tend to have some kind of documentation and infrastructure for assisting new contributors - a mailing list, IRC channel, or other forum where you can find existing contributors and ask them for advice on what projects to tackle. For example, MediaWiki, Mozilla, and LibreOffice are name-brand projects that would probably look nice on a resume and also have some explanation of how to contribute documentation.
And yeah, OpenHatch's database might be the closest thing available for a database of projects asking for help - it encourages projects to list themselves, and it indexes their "bite sized" bugs that are good for new contributors. You can start on the OpenHatch search page, click "documentation", and see if any of those bite-sized documentation tasks looks fun to try. (And I volunteer my own skills helping OpenHatch, yay!)
posted by dreamyshade at 12:53 AM on January 29, 2014 [7 favorites]
XBMC is fantastically useful and almost impossible to figure out -- because it seems to be infinitely configurable, everyone's got a different configuration, and all they talk about in their "documentation" (mostly people's homemade videos) is how configurable it is. A real, comprehensive, techie-friendly-but-non-otaku tutorial manual that takes the reader from zero to competence would be a godsend. Settle on the standard configuration (I think it's called "Confluence") and cover that to begin with.
posted by Harvey Kilobit at 1:29 AM on January 29, 2014
posted by Harvey Kilobit at 1:29 AM on January 29, 2014
If you want a bleeding edge product, Laika is an integration test framework for the up-and-coming Meteor platform. Its documentation is so incomplete that I can't imagine many people have the patience to climb the learning curve. It is both conceptually difficult to understand/describe and is lacking any non-trivial code examples.
Other than learning new concepts, the biggest challenge will be that its user community is fairly small (partly due to its age, partly to the lack of documentation), so it may be challenging to find developers and users to help you gather the information you need.
posted by Mr Stickfigure at 4:59 AM on January 29, 2014
Other than learning new concepts, the biggest challenge will be that its user community is fairly small (partly due to its age, partly to the lack of documentation), so it may be challenging to find developers and users to help you gather the information you need.
posted by Mr Stickfigure at 4:59 AM on January 29, 2014
The Selenium project's documentation could use some love. I particularly find it confusing how this site combines information about all the different Selenium projects (RC, IDE, Webdriver) into one giant master doc, yet the Webdriver API documentation is in a completely different place. Also, the Ruby bindings for Webdriver are not regularly updated, which may also be true of the Python bindings.
Ditto with easyXDM.
posted by deathpanels at 5:23 AM on January 29, 2014
Ditto with easyXDM.
posted by deathpanels at 5:23 AM on January 29, 2014
Checkout the most popular projects on GitHub, and see if there's one you like.
posted by blue_beetle at 5:55 AM on January 29, 2014
posted by blue_beetle at 5:55 AM on January 29, 2014
Shibboleth is one that I could never figure out where to start. It's a wiki that is both light on details and overly technical all at the same time. It's got a big market in higher education and often times you find small institutions that have one and have no idea how to manage it.
posted by advicepig at 8:00 AM on January 29, 2014 [1 favorite]
posted by advicepig at 8:00 AM on January 29, 2014 [1 favorite]
A (re)tweet from @readthedocs (https://readthedocs.org/) might bring up some responses directly from people involved in projects that could use help. Plus, you know going in what sort of doc infrastructure they have.
Fractured Atlas (about) has two software projects. Only one of them is open-source, but both are created with the intent of supporting independent arts creators and orgs. Spaces: Rehearsal and performance space listing and reservation. Artfully: Event ticketing (Open source). They use zen-desk for documentation, and IMHO much of it could use review, and ideally presentation in some form other than the KB format.
posted by Jack Karaoke at 10:50 AM on January 29, 2014
Fractured Atlas (about) has two software projects. Only one of them is open-source, but both are created with the intent of supporting independent arts creators and orgs. Spaces: Rehearsal and performance space listing and reservation. Artfully: Event ticketing (Open source). They use zen-desk for documentation, and IMHO much of it could use review, and ideally presentation in some form other than the KB format.
posted by Jack Karaoke at 10:50 AM on January 29, 2014
Is OpenHatch better than SourceForge for someone to volunteer on projects? I usually send tech comm students to SourceForge.
posted by jadepearl at 5:51 PM on January 29, 2014
posted by jadepearl at 5:51 PM on January 29, 2014
Response by poster: Well, I've now gone from not knowing where to start (in a bad way) to not knowing where to start (in a good way). Outstanding recommendations and advice. Thank you, MeFites. Research begins now...
posted by 27 at 1:51 PM on January 30, 2014
posted by 27 at 1:51 PM on January 30, 2014
jadepearl: I'd say link them to both SourceForge and OpenHatch! SourceForge is more oriented toward people looking to download software instead of contribute to software, but it's probably a reasonable way to find out what kinds of open source projects exist, since it has a big catalog of them.
OpenHatch is designed to be welcoming for prospective contributors, with "training missions" that can help people get comfortable with using contribution tools, and a volunteer opportunity finder that lists projects that have expressed interest in getting help from newcomers.
You can also link them to Github's "explore" page and 24pullrequests, which offer even more options for finding cool projects.
posted by dreamyshade at 2:30 PM on January 30, 2014 [2 favorites]
OpenHatch is designed to be welcoming for prospective contributors, with "training missions" that can help people get comfortable with using contribution tools, and a volunteer opportunity finder that lists projects that have expressed interest in getting help from newcomers.
You can also link them to Github's "explore" page and 24pullrequests, which offer even more options for finding cool projects.
posted by dreamyshade at 2:30 PM on January 30, 2014 [2 favorites]
I thought of another one. If there is any project in the world that could use some help in the documentation department it is keepalived.
Super useful project used by everyone, yet documented by no one.
posted by tracert at 7:09 PM on February 12, 2014
Super useful project used by everyone, yet documented by no one.
posted by tracert at 7:09 PM on February 12, 2014
« Older I need help finding a venue for group dinner in... | Los Angeles: good greeting cards? Newer »
This thread is closed to new comments.
Then again, the problem there (broken links proliferating on the apache site, the protocol documentation or lack thereof, etc.) is probably beyond techwriter scope.
posted by rr at 9:04 PM on January 28, 2014