Barbara's taking some well-deserved vacation time this week. Here are
her notes from the summit:
OpenSolaris Developer Summit 5/3/08
Notes recorded by Barbara Lundquist
Notes from Advocacy Board Panel Discussion
-----------------------------------------------
Most of these notes are from the documentation discussion on 5/4/08.
However,
I'm including these docs comments from the Advocacy Board panel discussion:
- How can we support the user groups?
- Translate the materials.
- Create classroom packets like the lego packets
- Do screencasts for newbies
- Include user group blogs on the docs site
- Have docs page post the "latest news" and link to blogs with
technical info
- We, as Solaris users, need to take the time to learn about all the
applications
so that we can tell people how to use these applications on
OpenSolaris.
- Docs needs a "cookbook with recipes" about how to setup desktop,
mail service...
all the sys admin tasks need documentation
Notes from Documentation Discussion
---------------------------------------
* Michelle has additional notes from Saturday evening informal discussions.
The following docs are needed:
1 - We need to explain OpenSolaris for Linux sys admin users:
How do I do the sys admin/Linux tasks on OpenSolaris. (i.e. How do I do
the tasks I do on Red Hat?)
- How do I perform an augmented installation?
- We need to use common language in the docs, so that non-Solaris
users will understand.
i.e. Alot of the domain language is unique to Solaris.
- We need more comparison information the clarifies how
OpenSolaris is different from
other OS. We need to help the typical Linux sys admin person
by showing them
the Linux/OpenSolaris comparisons in terminology and tasks.
(Speaker will email specific comments to Michelle.)
- Per David Lindt, we need top map what users know in Linux tasks
to OpenSolaris -
to build the connections.
2 - We need to help our Solaris install base move from Solaris to
OpenSolaris. (The install base,
not just developers.)
- Create an "on-ramp" for moving from Solaris to OpenSolaris.
- Provide comparison between Solaris and OpenSolaris
- Help Solaris sys admins get up to speed on OpenSolaris
- Provide "what's new" in OpenSolaris.
- Explain the impact that the OpenSolaris modifications have for
users. - API docs for porters is needed.
3 - Docs needs to provide a "cookbook with recipes" for OpenSolaris users.
- Don't just provide a book. Instead provide a doc format where
"recipes "how tos"
can be easily submitted, referenced, and kept updated.
- The target audience should be the students and university
teachers.
- Cookbook should provide the basics for OpenSolaris users.
- Provide description of the differences between systems.
- Provide practical "how to" information.
i.e. Recipes for how to setup a desktop as a mail server,
as a developer machine, as a web server
- Student materials are, to a certain extent, marketing materials.
- blogs at sun.com as examples of "recipes"
- Docs should make a list of needed recipes (short "how tos") and
search the blogs for these procedures.
Then, docs should make a page that consolidates and formalizes
the blogs information.
- Ben, from advocacy group, spoke about a cookbook/recipe model
that he has used:
- recipe template provides for problem statement, solution,
and discussion.
- The cookbook/recipe model lowers barriers to contributing
documentation. Users can
contribute one "how to" recipe instead of developing a whole article.
* Note from Barbara: I think this is cookbook/recipes idea is the
most exciting idea from the discussion!!
4 - Docs need to provide 2 books or doc trains: 1 for education and 1
for problem solving user's needs.
5 - Docs must explain "Why OpenSolaris" and "How you will benefit from
OpenSolaris".
6 - Docs should provide information for tips on how to migrate from
SPARC Solaris
to Intel Solaris.
- The Intel rep (David) commented that Intel could help
contribute to this information.
Sun could send draft of tip to Intel staff for their input.
- For example, document how to move a suite of software
applications from SPARC
to Intel. This is SW documentation, not hardware documentation.
-We have these docs, but they haven't been updated in 3 years.
7 - Need What's New information.
Specific docs comments:
1 - When user is building packages, they need the package description at
the command line,
not just in the IPS GUI.
2 - Explain new model of getting packages from other repositories.
- What other repositories are available? List them as FYI.
3 - Expand Getting Started on the Live CD to cover:
- Do you want to ...., or do you want to...?
- Provide basics and provide pointers
- Add icon on the desktop for docs.
* Docs staff reported that Getting Started is icon on the Live CD.
4 - Users don't know how to configure the network stack.
Ben, from advocacy group, plans to do a screencast on this topic.
How can docs support the OpenSolaris community?
1 - What will be the docs guidelines and requirements for core
contributers (non-Sun) to include
documentation when they submit engineering contributions to OpenSolaris?
- Docs staff advises that there will be a tiered level of
documentation that is required to be
included with a contribution to OpenSolaris, depending on how
"core" the product is.
The baseline is that man pages are required for product delivery.
- What will be the procedure for delivering this documentation?
- Docs needs to define the new model for this - find middle
ground between having a process
that is too cumbersome for non-Sun contributors, but without
diluting the quality of documentation
coverage for Solaris products.
- Currently, interfaces need man pages. What docs are needed if
you are just adding
packages?
- Perhaps docs should develop and provide a questionaire for
contributers. The questionaire
will ask contributors to explain the goals of their package
delivery. Based on their answers, docs will
advise what docs will be needed by users of the submitted
packages. Include languages question.
2 - Docs should provide tools and templates for contributors to use in
developing their documentation.
3 - Docs should provide more "how to get started" information for
contributors.
* Docs staff reported that we have new documentation for Web Stack and
for Dev tools.
4 - Docs must explain to application developers that they need to
provide a man page that explains
what their application is and how to use it.
5 - David Lindt commented that we need to expand Application
Developer's Guide to cover IPS packages.
6 - Docs staff reported that bugzilla has categories for documentation
bugs and defects.
7 - If user has pieces of information that should be added to the
OpenSolaris documents, where, when, and how
do they submit this information?
- Docs staff reported that alot of the current docs are done by
Sun, but we hope for
more docs contributers.
- Cookbook/recipe idea: Let contributers submit a short how-to recipe
using the cookbook template.
- Should contributers be able to throw their procedures or blogs onto
a docs wiki? Genunix docs are separate from OpenSolaris docs.
Is that causing fragmentation of information?
General comments about Solaris and OpenSolaris documention
1 - The d.s.c. documentation is overwhelming - too long and too complex
for beginners.
The one piece of information that the user needs is buried in the d.s.c.
docs.
2 - Users need short introductory documents and short advanced documents.
* Tim Cramer comments that docs should do focused 3-page guides for
specific
Getting Started topics.
3 - Docs needs to provide multiple document chunks targetted for various
audiences.
Can those chunks be shared between targetted documents?
4 - From Ben, regarding advocacy:
- Big kukos for Michelle's running of the docs community in OpenSolaris.
- Docs are the most important tool for advocacy. People need to find
answers to their questions promptly.
- IBM redbooks are amazingly good.
5 - Basic and Advanced Sys Admin Guides are useless and need to be
destroyed.
6 - Solaris docs push "all the ways to do things" at you "all at once".
Users need
a graduated entry into the docs. If I'm a brand-new user, what is the
adequate
information that I need.
7 - The theory information in the Solaris docs are boring.
8 - Too much information and very hard to find information in Solaris docs.
9 - There's alot of product-specific documentation on sun.com that is
hard to find.
10 - Documentation information on BigAdmin is isolated from other docs.
11 - Blueprints were a great resource that should be revived. Users need
to hear
from the expert (engineers) on topics.
12 - Docs need to consolidate the information that is on wikis. What
goes where?
Users don't know where to put their information, so they put it in their
own blogs
instead. Then they get frustrated that they write blogs that aren't
being seen.
13 - Docs needs to find ways to acknowledge and reward contributors,
including
blog contributors. Bloggers need to be encouraged to continue and
reminded that
people are using their blog procedures, even if the blog doesn't get
alot if hits.
alan wrote:
> First of all, thanks to everyone who participated in the doc discussion at
> the OpenSolaris summit in Santa Cruz (5/3-5/4). It was great meeting you and
> hearing from the proverbial horse's mouth what you think about OpenSolaris
> docs and the direction we should be heading.
>
> More specifically...this is great input, Sriramn. Thanks for writing all of
> this down. We're always eager to hear from users with info like this.
>
> Barbara Lundquist, who co-authored the Gettign Started Guide along with
> Jyothi Srinath, has some detailed notes from the doc discussion at the summit
> that echo some of Sriramn's comments and others. Barbara, could you send
> those along to this thread?
>
> I've been trying to synthesize what I heard at the Summit and CommunityOne
> and related events, so I'd like to summarize a few thoughts, specifically
> with regard to OpenSolaris content. I've got a few bullets of high-level
> statements with a bit of commentary after each bullet.
>
> * Transfer knowledge from other OS users to the OpenSolaris user.
>
> As I heard it, we're talking about knowledgeable users here who know how to
> do things in Linux, or even Solaris. So, it would be helpful to tell them
> what's different about doing those things in OpenSolaris. The discussion
> focussed on system administration tasks, but I think we could extrapolate to
> include developers, too. In this discussion, folks mentioned both the need to
> compare/contrast tasks as well as map terminology where it differs from Linux
> -> OpenSolaris or Solaris -> OpenSolaris.
>
> (See Sriramn's inputs on specific docs of interest.)
>
> * Try to distill a set of common, required tasks and present in
> self-contained cookbook/recipe format.
>
> I take this to be a request for more modular doc components. There was
> discussion that this format would be easier to digest for
> students/professors, but I think there's some general interest in this
> approach. Folks seemed to like Problem Statement/Solution/Discussion format
> for presenting this info. There was also general belief that these would both
> simplify access for the user and would lower the barrier of entry for
> potential contributors.
>
> * Broaden the audience we're writing for.
>
> While we have a pretty advanced product, and there's a large population of
> experienced Solaris folk, there are new markets and target users who may not
> be steeped in the lore of Unix. As I recall, there were multiple calls for
> beginner documentation and simple explanations of things we might otherwise
> take for granted as experienced users.
>
> * Focus on migrating applications from Linux and Solaris to OpenSolaris.
>
> I think this comes in a couple of flavors. There's the software
> side...porting apps that currently run on Linux to OpenSolaris. And then
> there's a hardware component, since (in the Solaris case) this suggests
> porting from SPARC -> X86.
>
> I've got more, and there are other topics, especially with regard to
> nurturing community contributions, but will save those thoughts for another
> thread.
>
> -alan
>
>
> This message posted from opensolaris.org
> _______________________________________________
> docs-discuss mailing list
> docs-discuss at opensolaris.org
--
Diane Plampin
Manager, Information Products Group
- Information Program Management
- man Pages
- Solaris Install
- Open Solaris
ph. 303-974-3290 (67793)
