release documentation confusing for 9.1

[Aristedes Maniatis]

Kevin Oberman wrote:
> On Tue, Jul 31, 2012 at 5:52 PM, Aristedes Maniatis<ari at ish.com.au>  wrote:
>> Could I ask that someone with appropriate access rights review the state of
>> release documentation for 9.1 beta. It is very confused.
>>
>>
>> 1. This page is the best information available:
>> http://www.freebsd.org/releases/9.1R/schedule.html
>>
>> 2. The link from the front page ( http://www.freebsd.org/ ) is labelled
>> "Upcoming: 9.1-BETA1" but goes to a page which is mostly about existing
>> releases, not the next release. http://www.freebsd.org/where.html#helptest
>>
>> 3. Clicking on the "view" link for the 9.1 information on that page takes
>> you to http://wiki.freebsd.org/Releng/9.1TODO which looks a lot like the
>> information in point [1] but wrong/old.
>>
>> 4. On http://www.freebsd.org/where.html#helptest there is a link to "FreeBSD
>> Snapshot Releases" for people interested in "FreeBSD-CURRENT (AKA
>> 10.0-CURRENT)". But following the link takes you to a page where you get
>> linked to "9-CURRENT, 8-STABLE, 7-STABLE, and 6-STABLE" snapshots.
>>
>>
>>
>> It is possible I'm just stuck in the past, but I've never been able to
>> navigate the 'new' bowling ball branded FreeBSD site nearly as well as the
>> older incarnation. And yes, I can eventually figure it all out... but this
>> information could be a whole lot clearer. I design information presentation
>> for a living, so perhaps I'm picky about these things, but I do think that
>> confusion could turn people away from my favourite operating system.
>>
>> I'm happy to help if someone wants to enlist my assistance, but I don't
>> currently have any commit rights on this project.
>
> RE has not done very well in updating this stuff for several releases.
> RE is a very hard job and I understand that they are busy with both
> 9.1 and $REAL_JOB. I'd love for them to find someone whom they trust
> and with reasonable clue to whom they could give the right to update
> all of this stuff. It would still lag a bit, but it would be closer.
>
> As far as what will be in 9.1, the doc tree was tagged for 9.1 two
> days ago and can be downloaded from svn or cvs and built. Note that
> it's all in sgml and you need to build the various formats. I'm not
> sure when they will hit the web site and, of course, noting is
> official until the release, but it is unlikely to change at this point
> except for minor corrections.

Thanks Kevin

I think that perhaps the first job (when everyone isn't busy with releasing) is to examine the relationship between the wiki and the website, make sure everything is well organised, and make sure it is trivial to update by the release people. Beyond that, the actual structure of pages within the website doesn't make sense (to me) and isn't particularly clear from the home page.

Analysis of web logs might give some insight to what people are looking for and viewing on the freebsd site (although of course, doesn't tell you what they are just unable to find despite searching for it).

Over at Apache, the infra people have moved our project websites to a svn pubsub approach which works well with the established user base of developers who know svn. Updating pages becomes fairly trivial and a web rich text editor interface means it is even easy if you are away from your regular toolset. Whatever the process, it has to be easy enough that RE can fit it into their workflow without additional burden.

Ideally, scripts could detect the release tags in svn and update the website automatically.

Cheers
Ari