Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Improving documentation of open source software

futurice.com

Post reply on HN
Print view View original

1–10 of 20 posts

Re: Improving documentation of open source software

#2

Post by softwaredoug »

In addition to docs, I’d also add evangelism as often missing. For a project to be successful, someone fronting the project and engaging with a potential community on how it could be used. Call it “sales” or “marketing” even, but open source projects need it as much as proprietary products...

Re: Improving documentation of open source software

#3

Post by gav »

softwaredoug wrote: post #2

In addition to docs, I’d also add evangelism as often missing. For a project to be successful, someone fronting the project and engaging with a potential community on how it could be used. Call it “sales” or “marketing” even, but open source projects need it as much as proprietary products...

There's a list of things that should be right there on the project homepage:

- What is this project?

- Who is the intended audience?

- Why would I use it?

- How does it compare to other projects?

- Where should I go for help/support, i.e. where is the mailing list/forums/etc.

- How can I get up and running with the minimum of effort?

Re: Improving documentation of open source software

#5

Post by naniwaduni »

softwaredoug wrote: post #2

In addition to docs, I’d also add evangelism as often missing. For a project to be successful, someone fronting the project and engaging with a potential community on how it could be used. Call it “sales” or “marketing” even, but open source projects need it as much as proprietary products...

Evangelism is needed if adoption is a goal, which is far from a given even for proprietary products.

Re: Improving documentation of open source software

#7

Post by andrewingram »

gav wrote: post #3
softwaredoug wrote: post #2

In addition to docs, I’d also add evangelism as often missing. For a project to be successful, someone fronting the project and engaging with a potential community on how it could be used. Call it “sales” or “marketing” even, but open source projects need it as much as proprietary products...

There's a list of things that should be right there on the project homepage: - What is this project? - Who is the intended audience? - Why would I use it? - How does it compare to other projects? - Where should I go for help/support, i.e. where is the mailing list/forums/etc. - How can I get up and running with the minimum of effort?

- why might I not want to use it?

Re: Improving documentation of open source software

#8

Post by steveklabnik »

softwaredoug wrote: post #2

In addition to docs, I’d also add evangelism as often missing. For a project to be successful, someone fronting the project and engaging with a potential community on how it could be used. Call it “sales” or “marketing” even, but open source projects need it as much as proprietary products...

I cannot agree more.

It’s simultaneously something that’s incredibly important, but also weirdly under-valued.

Re: Improving documentation of open source software

#9

Post by brewdad »

andrewingram wrote: post #7
gav wrote: post #3

Earlier quoted context omitted.

There's a list of things that should be right there on the project homepage: - What is this project? - Who is the intended audience? - Why would I use it? - How does it compare to other projects? - Where should I go for help/support, i.e. where is the mailing list/forums/etc. - How can I get up and running with the minimum of effort?

- why might I not want to use it?

I really appreciated the "drawbacks" link on the sidebar at migadu.com. If you know there are use cases that don't fit your goals, admit them up front.
Post reply on HN