I agree with Shawn's observation that documentation should live wherever
it is useful. I may not have been clear about that in my initial
suggestion. I just think it would also be good to have a location where
people can go and scan an index of all of the documenatation on the
site. As I've thought about this a little more, I realized that the
archive pointer for articles, for example, will still go to the articles
page that currently exists. I'm just proposing an index to make all
documentation more readily accessible and easy to find(that's the goal
anyway :) ).
I also like Rich's idea of having a documentation link added to the LH
nav bar. That would provide a great portal to the archive.
Thanks for hiring me Jim. :)
Ginnie
Jim Grisanzio wrote:
Virginia Wray wrote:
Hi -
I would like to throw out a suggestion. I think that the documentation
on the site is already becoming scattered in a way that is going to
make it less user friendly for people to find what they are looking
for. I did a page-by-page look for all documentation on the
OpenSolaris site, and I found documentation on about 4 different
pages. Although that doesn't seem like much, if someone is looking
for something and can't remember where they saw it, it will be
frustrating. If this is perpetuated, it's going to be even more
difficult to consoldate down the road.
I think there is an argument for moving documentation to one community
so it's easily found, but as we grow and diversify it may make sense for
some documentaiotn to be community-specific and live within a certain
community. However, the documentation community may want to track all
this and point to it.
I think it is worth considering consolidating the documentation onto
the community documentation site and providing pointers to them from
the places where they are now located. Additionally, move the articles
on the articles web page to the community documentation site instead
of having a separate web page for it.
I'm ok with this as long as it's clearly distinguished from the document
ion. A non-tech guy like me would not read Rich's build article but I'd
be more interested in reading *about* Rich and what makes him a really
cool guy. I need to be able to find that sort of content as easily as a
developer needs to be able to find how to build OpenSolaris. One of the
reasons we wanted to produce some articles (magazine-style, I mean) was
to reach out to a more broad audience than coders.
I think if we create a centralized
archive from the start, it will keep the documentation well-organized
and easy to find and use.
I think we can do something like this, but I'm not clear yet what it
would look like.
I'm happy to help work on this if it sounds like a good idea to others.
Good. You're hired. :) And thanks for your suggestion.
Ginnie
Jim Grisanzio wrote:
Ben Rockwood wrote:
Jim Grisanzio wrote:
Ben Rockwood wrote:
Jim Grisanzio wrote:
I did a little blog pointing to the articles on opensolaris.org:
http://blogs.sun.com/jimgris?entry=some_articles_on_opensolaris
We'll eventually have to link to these from the front page. There
are few more articles written and in review (Solaris on laptops,
a 3rd driver article, a kernel comparison, and a piece on
portability. We'll release those as soon as they are done.
For those of you who are new to the community: we had some
articles written (some light technical, some community profiles,
etc) during the pilot program, and we'd like to continue that
function if you are interested. Are you? If so, what publishing
model is best for this community? Who are the writers out there?
When I say that I mean are you interested in contributing
articles, and how would you like to be recognized for that
contribution? And if so, would you like to help work on an
editorial plan to get us going past what we already have? I think
we need to figure out a way to incent people to contribute (to
write/edit/review) things like how-tos, profiles, case studies,
opinion pieces, feature articles, news, etc. In terms of style,
I'm thinking that the more magazine-like the better to
distinguish this editorial from documentation.
We are working on a website editorial policy to sort of outline
who does what and where on the site generally. This "articles"
section I'm talking about is just one part of that, but we really
began it back in the pilot program. It'll all come together over
time.
Opinions?
Question... did Sun pay for those profiles?
Yes.
If so, why?
We contracted with O'Reilly (two editors, in fact) during the pilot
program for the articles based on their work with other Sun open
source projects, most notably java.net. That contract has come to
fruition, so I'm looking for a new way to generate some content.
"Why" specifically is more difficult. The thinking back last year
was to make the site more of a magazine-style feel based on
java.net but customized for Solaris and the OpenSolaris community.
Offering that is one of Oreilly's services. The original vision
never really materialized, so what we have is a series of articles
to build from.
This is just the opinion of one, and take it with as much salt as
you like, but... I strongly feel opposed to OpenSolaris having ties
like this.
I think we'll have to develop many ties to various communities for
the purposes of collaboration. Including O'Reilly. Love 'em or hate
'em they are part of the open source community, just as are we. Their
style may not be right for OpenSolaris at this early time, but that's
ok. Perhaps we'll meet up in the future. No big deal. They have
helped us a great deal in some areas, especially early on by
providing access to key open source people for the purposes of
feedback sessions (way before the pilot began). They also helped
provide speakers for Sun's Open Source Conference in Santa Clara last
summer. They've helped out in other ways, too. They article thing
wasn't as successful, but it doesn't mean we can try again with a new
model ourselves or even re-engage O'Reilly in the future.
Its obvious from the profiles that the authors researched the
persons they profiles instead of knowing them. They read very
professionally, sure, but flat and contribed.
An editorial relationship takes time. Editors need time to build a
writer base and get to know sources, etc. That never really happened
here, but it could happen and should happen and it's what I had hoped
would happen.
OpenSolaris isn't a
product to be marketed the same as Java with sponsoring ties, farm
outs, etc, but something entirely diffrent that must be maintained
as pure. Cutting a deal with O'Reilly or any other company for that
matter just seems to cheapen the whole project. It seems shallow,
like we have to buy friends or something.
I don't think we were buying friends as much as we were simply
looking to engage with a friend and try something to help the
project. Sun has extensive business and developer relationships with
O'Reilly, and so it made sense to engage -- albeit at a very, very
low level. Why wouldn't we want to talk to O'Reilly's network of
developers? It's pretty substantial. Hey, I tried. Take it as that.
Nothing more. I argued early on this project that the entire web site
needed an editor to manage all the content (for consistency, style,
flow, graphics, etc). I'm even more convinced of that position today,
although very few share that view so I've decided to not argue the
point actively any more. Maybe we'll get there in the future. Maybe
I'm wrong.
Take those bucks and buy back some shares or
give out some more tshirts, that'd help us all much more I think.
Like I said, plenty of salt on that please.
Understood. :)
I'm not sure if anyone else
feels the same.
I would, too, actually. :) If the community is not interested, I'll
drop it and move on. There's plenty to do around here. :) I just
wanted to bring it up one last time now that we are open and out of
the pilot phase.
Reguarding the rest, I can write when time permits. Plenty of us
are producing useful information, but "articles" in the
traditional sense conflict directly with technical blogging. Many
of our blog entries could be slightly reformed and presto-change
you've got an article.
I agree. But we need to lay out a 6 month or year long editorial
plan to pro-actively generate the content. We can also just re-work
previous blogs (the substantive ones) for articles, too. Good
suggestion.
Is there any chance we could see a draft of this editorial plan?
I circulated drafts of the plan (which I wrote, not O'Reilly) back in
the early pilot days. Very little response so I didn't press it. It
was basically a list of article suggestions. I just worked with
O'Reilly to implement what we had, and so we got 11 articles (8 of
which are posted now with 3 to go). There is no plan right now, though.
Perhaps if we could all take a look we could all see what parts of
it we could contribute to and all pull together to provide real
community content. It might not be as professional as if it were
done by professionals, but it'll be ours.
Yes. I'd like to create a *new* editorial plan -- if the community
wants this. Although I'm convinced we need this function, I'm not
convinced the community wants it. So, perhaps if we kick around a
plan to produce a series of articles in various categories we can all
own it and implement it.
The Driver Programming articles by Max are awesome, I'd love to
see more of those.
He has two more in the works.
Didn't Rich have some articles in the pipe too?
Rich did a dev piece for the Studio tools guys separate from what
I've been trying to do.
Anyone have a url? (or if its unreleased a timeframe?)
http://opensolaris.org/os/community/tools/building_opensolaris/
benr.
_______________________________________________
opensolaris-discuss mailing list
[email protected]
_______________________________________________
opensolaris-discuss mailing list
[email protected]
