Jim Grisanzio wrote:
> I'm involved in the program, and I wanted to ping this list specifically
> to see if the docs community would like to be actively involved as well.
> I suggested a docs category initially just as a place holder because I
> thought it was an important part of the community. But ultimately the
> desire would have to come from this CG. I'm just giving a heads up
> because time is tight. :)
I don't have the bandwidth to contribute much to this right now, but
wanted to encourage thinking about documentation in the wider scope,
and framing the awards to cover both writing documentation and finding
new ways to create and deliver it.
For instance, I think these could all be great projects:
- DTrace has an excellent reference manual, but could use a tutorial or
users manual. I'm sure it's not the only part of the system that
could use similar work.
- Coming up with a standard for documenting Dtrace providers/probes
in man pages, and then implementing it for the ones shipped in
OpenSolaris. For instance, when I did the X server provider,
I had nowhere appropriate to document it, so even today, the
official Sun docs just point people to my web page at
http://people.freedesktop.org/~alanc/dtrace/
- I've always liked the PHP manual's style of having the documentation
only editable by the project, but allowing anyone to add comments
with examples, clarifications, best practices, etc. for instance:
http://us.php.net/manual/en/function.preg-replace.php
Could we do something similar with OpenSolaris documentation? Should we?
- When Solaris first switched to SGML man pages, one of the rationales
was to allow development of a hypertext/curses man command, more like
GNU info, but no one has ever written it. Is now the time?
- Some open source projects are moving to DocBook/XML as their preferred
documentation format - what will it take to integrate these into the
SolBook/SGML docs/toolchain that OpenSolaris has? (I know X.Org is
going this way, slowly, and believe other communities are as well.
We're missing some of the tools in OpenSolaris that make this much
easier on other platforms, like "xmlto".)
- Project Indiana is talking about a refactoring of the OpenSolaris packages,
including (I think) putting the man pages in the same package as the
software, much like most Linux packaging systems do - what has to happen
to the docs & tools to make this work well? And how are we going to
get the package name in all the attributes sections of the man pages
updated? (Preferably automatically.)
- Are there any parts of the documentation that are still encumbered that
need open source replacements created for them?
- We've seen a huge influx of outside open source projects incorporated into
OpenSolaris distros, from core pieces of the desktop like X.Org and GNOME,
to the entire open source WebStack (apache, ruby, python, etc.) to all
sorts of small add on tools - how do we get their documentation better
integrated with the OpenSolaris docs, but without requiring a lot of
manual intervention, because the rate of bringing this stuff in is
going to increase.
- One of the things I've always hated about docs.sun.com is that the process
always seemed to be stuck in the paper manual era - the docs were written
and released with the product, and then not changed until the next release
of the product. (I've heard this may have gotten better lately, since I'm
not involved with any docs published on docs.sun.com, I haven't followed
it closely.) If bugs were found or customers had issues with the
product that should be documented, we didn't take advantage of the power of
the web to update them immediately in place - how do we do better for
docs.opensolaris.org? (Could be as simple as the PHP example mentioned
above, or could be something else.)
- Solaris documentation for customers is not just docs.sun.com, but a whole
series of InfoDocs and other documents on SunSolve - what should the
OpenSolaris equivalent be?
- Personally, I never listen to podcasts, since I don't really have the time,
and have always been more of a visual than auditory learner (I can read
much faster than I can process spoken language), but I know people who love
them - they listen in their cars while commuting, or on their MP3 players
while working out. How can we provide tutorials or other information on
OpenSolaris technologies in this format for them to listen to?
- Our documentation in English is great, but OpenSolaris is growing faster in
places where English isn't the first language - how do we better serve
those communities?
--
-Alan Coopersmith- alan.coopersmith at sun.com
Sun Microsystems, Inc. - X Window System Engineering
