Date: Wed, 27 Nov 2002 20:13:42 +0000 From: Nik Clayton To: Niklas Johannes Saers Subject: Re: FreeBSD documentation project Parts/Attachments: 1 Shown ~97 lines Text 2 194 bytes Application ---------------------------------------- Hi, On Mon, Nov 25, 2002 at 01:32:52PM +0100, Niklas Johannes Saers wrote: > my name is Niklas Saers (and I'm also called Nik by my english speaking > friends :) ) and I'm currently writing my master thesis on the FreeBSD > project. What I'm writing is a methodology for the FreeBSD project based > on its current status and then a discussion of this. I hope to have the > methodology written up for critique by the people who've helped me through > interviews by early january and available to a more widespread critique > end january. When it's all done, I hope that parts of my thesis will be of > value to the FreeBSD documentation project (it's due in May), and I'll of > course reformat and adapt it so that it can serve the most value to the > readers. Great. > Anyways, enough about the status. I'm writing to you concerning the > documentation project. Through my digging through the mailinglists, I've > found that the documentation team started out in January 1995 with no > leader, 4 team leaders and 16 regular members, having the requirement that > the leader should be a part of FreeBSD core. The project leader should > have at least quarterly discussions with the team leaders where they > define and follow up goals. I never knew that :-) Can you send me a link to the (presumably) mailing list archive where you found that -- it's an interesting piece of history. > I was wondering if this is still the status > today. How many are involved in the project, how many leaders are there > (from http://www.freebsd.org/doc/en_US.ISO8859-1/articles/contributors/staff-doc.html > it seems to like 10 to me), how many contributors are there? How many of > the project have commit access and how much activity is going on? What > routines do you have? What standards are being followed and what can you > tell me about the documentation process? OK, well things have definitely changed over the last few years. A non-scientific check (basically, looking at the number of unique committers to the doc/share/sgml/man-refs.ent file) shows 32 committers, which feels about right. I don't keep a complete count, because although some people specialise in just the documentation, others work on documentation, and maintain some ports, or do some work in the src/ tree as well. However, 30-35 certainly feels like about the right number of doc committers. That's about 10% of the committer community, but of course, all the committers can make documentation changes if they feel it's necessary. Contributors is a far harder number to measure, because anyone can send in a PR that fixes a typo in a man page, and then we never hear from them again. Last time I checked the doc@freebsd.org mailing list had just under 300 people on it, which is quite high. As to leaders -- well, for a while I haven't been able to give the project as much attention as I'd like due to increasing time commitments from other things going in on my life. This is not uncommon in the FreeBSD world. When FreeBSD was much smaller we had one release engineer (for a time, Jordan). We had one person responsible for the ports tree (Satoshi Asami), and there was me, co-ordinating the documentation efforts. Now the project and the size of the community have grown so much that it's impossible for any one person to keep a handle on all these things. So we have a release engineering team now, and a group responsible for managing the ports/ tree. We're in the middle of moving to a similar system for the documentation, where a team (consisting of some people from the release engineering team, and a representative from each translation team) will take over much of the administrative work (approving new documentation committers, tagging the doc/ tree when there are new releases of FreeBSD, and so on). We're still thrashing out a few of the details, but this will probably be announced more formally some time over the next couple of weeks. Most of the 'routines' and 'standards' can be found in two documents (both linked to from http://www.freebsd.org/docs.html). The first of these is the 'New committers guide', which explains how the project works for new committers. This explains things like how to commit, who does what, where to go for help, and so on. Documentation project specific information is covered in the Documentation Projcet Primer, which contains information about the format we use for the documentation, and useful tutorial information. Hope that helps. Feel free to ask any other questions, either directly to me, or on the doc@freebsd.org mailing list. N Date: Sat, 7 Dec 2002 14:53:24 +0000 From: Nik Clayton To: Niklas Johannes Saers Cc: Nik Clayton Subject: Re: FreeBSD documentation project Parts/Attachments: 1 Shown ~120 lines Text 2 194 bytes Application ---------------------------------------- On Wed, Dec 04, 2002 at 11:11:30AM +0100, Niklas Johannes Saers wrote: > Hi Nik, and thank you very much for taking the time to answer. > > > I never knew that :-) Can you send me a link to the (presumably) > > mailing list archive where you found that -- it's an interesting piece > > of history. > > See FreeBSD hackers mailinglist of Tuesday January 10th, 1995, 04:24:35 > This is a follow up to Jordan's announcement for the start of the project, > January 6th, 1995, 01:52:26. Thanks for that. I've dug those out of the archive. Interesting reading. > > A non-scientific check (basically, looking at the number of unique > > committers to the doc/share/sgml/man-refs.ent file) shows 32 committers, > > which feels about right. > > This number is CVS edits, right, thus including people no longer active? > How many active committers would you say there is at the moment? Is there > some way to figure this out? (any committer cvs activity monitors? :) ) 25 unique individuals made commits to the doc/ tree in the last month or so. % cd doc % cvs log -d 2002-11-01 | grep author: | awk '{print $5}' | sort \ | uniq -c | sort -rn | wc -l If you remove the final '| wc -l' you'll get this: 43 keramida; 23 mheinen; 21 alex; 19 murray; 13 ue; 10 nik; 8 peter; 8 des; 7 trhodes; 4 chern; 4 blackend; 3 mwlucas; 2 jim; 2 ache; 1 tom; 1 roam; 1 logo; 1 lioux; 1 fanf; 1 dd; 1 dannyboy; 1 cjc; 1 chris; 1 ceri; 1 adamw; Where the first column is the number of commits. > > I don't keep a complete count, because although some people specialise > > in just the documentation, others work on documentation, and maintain > > some ports, or do some work in the src/ tree as well. > > Right. But as I've understood it there are people who have only commit > priveleges in the documentation tree. Yes and no. Technically, there are no barriers to stop a (src|doc|ports) committer making changes to other parts of the tree (e.g., a doc committer making a change to the src/ tree). However, there are social structures in place -- typically, someone is bought in as a committer for one of (src|doc|ports), and are guided in the process by a mentor. If (for example), a ports committer wants to start making changes to the doc/ tree as well then they'll need to find a mentor from the doc/ project. > > Contributors is a far harder number to measure, because anyone can send > > in a PR that fixes a typo in a man page, and then we never hear from > > them again. > > Are people that send PRs regarded as contributors? Yes. > You say you aren't able to give the project as much attention as you'd > like and that this is quite common. Does this make room for other people > to become de facto leaders through their time invested, or temporarily > have more influence than other times? Definitely, and I think this is a good thing. Opinions don't count for as much in the project if you're not prepared to back them up by doing the actual work. > If so, do you feel this disrupts the Documentation project or the > FreeBSD project? Not that I've seen. > One thing I'm curious about is mailing lists. As far as I can understand, > the amount of mail on the different lists is far more than what project > members can read through every day, not to mention reply to. How much do > you read the mailing lists yourself, and how much would you say is common > for the members of the Documentation project, if not the FreeBSD project? This probably varies widely on an individual basis. I read advocacy, arch, committers, cvs, current, developers, doc, hackers, and stable, as well as the UK user group list. I tend to skim, looking for topics that are particularly interesting to me, and I'm sure a lot of other developers do the same.