Rockbox Development - Documentation

[karashata]

One thing I don't see anyone else having mentioned is that, being that the wiki is what it is, if you see any obvious discrepancies between what the wiki states and the actuality of things, you're always free to fix it yourself, though it may not be a bad idea to check in the IRC channel first (or perhaps mention it in the appropriate forum) to make sure that the change is appropriate. Often times, especially with older wiki pages, people may tend to forget about them and not end up updating them to reflect more recent developments.

[chrisjj]

> you're always free to fix it yourself, though it may not be a bad idea to
> check in the IRC channel first (or perhaps mention it in the appropriate forum)

Understood. I asked only because often "the appropriate forum" is one for documentation... and I saw no-one using any other.

> Often times, especially with older wiki pages, people may tend to forget about
> them and not end up updating them to reflect more recent developments.

The "who didn't do the washing up?" problem

One solution is assigning responsibility.

[Llorean]

Then I assign responsibility to you.

Seriously, it's a volunteer project, which means nobody has any enforcement ability. So, that's about as far as "assigning responsibility" can go. If you don't keep the wiki up to date, I guess we'll have seen how well the idea of assigning responsibility worked.

And as I told you before, "the appropriate forum" isn't one for documentation - it's the one for discussion of whatever the documentation was about. This shouldn't need repeating to you.

If you think the manual is bad, and it's in the section about controls, ask questions in the "user interface and voice" part of the forum. Then, if you satisfy yourself that the manual is incorrect, post a bug report in the tracker. It's pretty simple, and I don't see why you can't get a grasp on this.

Documentation is always about something. So discussion of the documentation about X is really discussion of X as well, and can go in that forum.

Can you think of a specific example of our documentation where there's not a subforum relevant to the documentation's subject? If there really is such a blind spot I'm sure discussion about opening up a relevant forum can be had.

[karashata]

One solution is assigning responsibility.

Actually, that's not really possible. No one person can be expected to know every aspect of the project, since it's actually quite extensive. The only real option is to have people like you either alert others to the discrepancies (either in the IRC channel or the appropriate subforum pertaining to the nature of the wiki article or manual entry in question), or to have people update the wiki themselves if they're sure of the changes being made.

As Llorean said, this is a volunteer project. No one can assign anyone to do anything. Even the developers aren't assigned anything specific, they work on whatever they have knowledge or interest in working on and go with it. I wouldn't be surprised if a lot of the developers have learned new things by working on this project that they wouldn't have learned otherwise in their jobs. (But that's starting to get a little off topic, so we won't go further there...)

[Confuseling]

As Llorean said, this is a volunteer project. No one can assign anyone to do anything.
...

I suppose that isn't strictly true - Debian, for example, is a volunteer project with (some) clearly defined areas of responsibility.

But Rockbox isn't Debian.

The thing that seems bizarre about this is that for an open source project, the Rockbox documentation is actually very well maintained... or at least the bits that I've looked at are.

@ chrisjj: he who pays the piper calls the tune.

The Rockbox devs, I am guessing, partly release their code out of self-interest; by collaborating with others, they receive reciprocal collaboration, and get better software than they could possibly write themselves. They also, I am guessing, partly release their code out of sheer desire to make something publicly useful.

You'll notice you and I don't do anything in this arrangement. The way it works - convention has it - is that they owe us nothing, and we try not to seem demanding in return...

[Llorean]

I believe though that in the context of Debian, people have probably volunteered for those areas of responsibility (and then been accepted by the maintainers of the project) rather than being assigned them directly.

[GodEater]

I can't see how that would work in any other way. You can't take a pool of volunteers and have someone say "Hey you, you're in charge of documentation now".

If someone did that to me here I'd tell them where to go.

[Confuseling]

My point was just that it does happen in larger organisations, at least in a small way, where whatever intangible benefits (such as prestige) to taking part outweigh the desire to 'do your own thing'.

If the people at the top of the Debian security team say "We need this thing patched NOW!", quite a few people probably jump up and take notice. They're volunteers, but they're still under direction.

However, Rockbox isn't Debian - which isn't to suggest that either model is better, they're just different.

-ETA-

Not sure if that's really clear. I guess what I'm saying is it's a question of 'granularity' as well. Nobody would put you on the Debian security team without your permission, in that sense you're both entirely correct - but once you've put yourself on it you forego the freedom to code whatever you feel like coding.

Bit off topic this... Sorry, I'll shut up. 

[chrisjj]

I can't see how that would work in any other way. You can't take a pool of volunteers and have someone say "Hey you, you're in charge of documentation now".

If someone did that to me here I'd tell them where to go.

I can well imagine Rockbox people might want to take on documentation responsibility, esp if it was divided appropriately. E.g. a user knowledgeable on a particular player could accept the job of overseeing that wiki sub-tree. When I started looking at the Sansa e200 docs I found stuff that had been written about all then-known versions , but invalidated by the subsequent AMS/v2 port. I see a coder who made the v2 port didn't feel the desire to make the required amends to the existing material, so I'd say that would probably get done promptly if there was in place a Sansa Wiki Guy/Gal.

[Llorean]

What, exactly, do you think is stopping people currently from volunteering for these types of jobs?

[chrisjj]

What, exactly, do you think is stopping people currently from volunteering for these types of jobs?

I don't know. How about you tell me?

[Llorean]

You're the one who proposes things should change. It's on your shoulders to identify how the current situation does not meet what you think it should be.

If you're not willing to do that, and just want to play the "you tell me" game, just stop posting and wasting peoples' times. Take it seriously and come up with a proposal for a new situation, then implement it yourself for the community documentation. It's that simple. If you aren't willing to put the effort into it, you should stop expecting anyone else will be.

So far you've basically just said "other people should do something" but haven't been explicit about what, nor done something yourself. I'd say it's about "put up or shut up" time.

[Strife89]

What, exactly, do you think is stopping people currently from volunteering for these types of jobs?

I don't know. How about you tell me?

How about the fact that a lot of people have lives away from their computers, which consist of various time-consuming activities that leave little room for work on something that they aren't getting paid to do.