Email or username:

Password:

Forgot your password?
Top-level
Shauna GM

@jrconlin @hyc @mhoye the solution to "there is a big gap between what maintainers provide and what users need" is not to ask overworked/underpaid FOSS maintainers to take on more responsibility. nor is it to deny the need exists.

the solution is for the broader community to recognize the value of user-facing, newcomer-friendly docs and dedicated user support, and to help maintainers provide them. that requires investment. it's part of the broader open source collective action problem.

3 comments
Ed W8EMV replied to Shauna

@shauna @jrconlin @hyc @mhoye

I can think of a couple of categories of things beyond the core code itself that are needed for the long-term health of a project:

- an accurate and detailed man page
- a "getting started" guide that deals with building, installing, and running some kind of "hello world" code to validate the install
- architecture documents that describe how and when to use the code
- a conference presentation aimed at a knowledgable audience
- full-length book

Rare to get all.

@shauna @jrconlin @hyc @mhoye

I can think of a couple of categories of things beyond the core code itself that are needed for the long-term health of a project:

- an accurate and detailed man page
- a "getting started" guide that deals with building, installing, and running some kind of "hello world" code to validate the install
- architecture documents that describe how and when to use the code
- a conference presentation aimed at a knowledgable audience
- full-length book

jr conlin —〰— replied to Ed

@w8emv @shauna @hyc @mhoye

I think it's also somewhat important to note scale. A tiny package used by a few folk probably doesn't need much more than what folk already do. This would probably not overburden that one guy in Nebraska.

Once a project "graduates", takes on devs, and grows in use, then documentation becomes more important, just like security updates. Large projects should help by reaching down to smaller ones that they depend on.

Go Up