Live data from Hacker News

Ask HN: What OSS projects need the most help with documentation?

news.ycombinator.com

11–20 of 24 posts

Re: Ask HN: What OSS projects need the most help with documentation?

#11
post #8

Pgpool-II is a powerful piece of software that allows people to connection pool a Postgres cluster, and is even capable of managing a full multi master cluster. The docs are, however, so badly written and incomplete that it's way too hard to set up for most people. A shame, because it's great stuff.

Bucardo (http://bucardo.org/wiki/Bucardo) is a along the same lines. It could really use some help improving documentation.

Re: Ask HN: What OSS projects need the most help with documentation?

#12
Just curious - as a contrary example, I would like to see links to a few OSS projects with exemplar documentation done "right". As an example, the Django project does a great job of treating its documentation as a "first-class citizen". While I have used OSS software and not developed, I would guess there are some good best practices / checklists out there for documentation (e.g. "what a good README should contain"; recommended tools to ensure documentation is easily contributable, versioned, and so on; "how to deploy this software", "how to install", architecture overview, "meta" documentation on how to contribute to the project, and so on). Would be good to see examples of those too. Thanks!

Re: Ask HN: What OSS projects need the most help with documentation?

#13
post #12

Just curious - as a contrary example, I would like to see links to a few OSS projects with exemplar documentation done "right". As an example, the Django project does a great job of treating its documentation as a "first-class citizen". While I have used OSS software and not developed, I would guess there are some good best practices / checklists out there for documentation (e.g. "what a good README should contain";…

https://github.com/showcases/projects-with-great-wikis

Re: Ask HN: What OSS projects need the most help with documentation?

#14
post #12

Just curious - as a contrary example, I would like to see links to a few OSS projects with exemplar documentation done "right". As an example, the Django project does a great job of treating its documentation as a "first-class citizen". While I have used OSS software and not developed, I would guess there are some good best practices / checklists out there for documentation (e.g. "what a good README should contain";…

[deleted]

Re: Ask HN: What OSS projects need the most help with documentation?

#15
post #12

Just curious - as a contrary example, I would like to see links to a few OSS projects with exemplar documentation done "right". As an example, the Django project does a great job of treating its documentation as a "first-class citizen". While I have used OSS software and not developed, I would guess there are some good best practices / checklists out there for documentation (e.g. "what a good README should contain";…

My understanding is that Docker has great documentation.

However, as a corporate sponsored project with multiple full time employees working on the documentation, it most likely fails your criteria in spirit.

Re: Ask HN: What OSS projects need the most help with documentation?

#17
I once added a few lines to Paperclip's README to promote a method I used from undocumented to documented. I thought it was a devious way to make them keep it around. :-) If you are looking for places to improve documentation, it's a nice selfish way to prioritize.

Re: Ask HN: What OSS projects need the most help with documentation?

#20
post #12

Just curious - as a contrary example, I would like to see links to a few OSS projects with exemplar documentation done "right". As an example, the Django project does a great job of treating its documentation as a "first-class citizen". While I have used OSS software and not developed, I would guess there are some good best practices / checklists out there for documentation (e.g. "what a good README should contain";…

Beets has great documentation:

http://beets.readthedocs.org/

Post reply on HN