Friday Jun 06, 2008
Saturday Jun 23, 2007
By dlindt on Jun 23, 2007
The Solaris Developer/Sun Studio tech pubs group has been talking about the information we provide for Solaris Developer and the Sun Studio compilers and tools.
Our group has been delivering information to a variety of places for a number of years. For Solaris Developer, we deliver books to the following collections on docs.sun.com:
- Solaris Developer collection
- Solaris Express Developer Edition docs collections
docs.sun.com performance has been pretty slow lately, so I'll finish the list of docs we deliver to docs.sun.com later.
What is really cool is that we have a variety of Solaris Developer and Solaris System Administration Guides available from the Documentation Consolidation (Docs) Download Center on opensolaris.org. The Documentation Download Center also has instructions for downloading the source to the books available on opensolaris.org.
We are also looking at doing more with technical articles, tutorials, information for new Solaris users, blogs, multimedia, and posting more info on opensolaris.org.
For Sun Studio, we have been delivering docs to the the Sun Studio 12 Documentation pages at developers.sun.com, the Sun Studio 12 docs collection on docs.sun.com, various blogs, and technical articles.
We have also been experimenting with a Solaris Developer group blog where we are trying to highlight various Solaris Developer and Sun Studio docs
So this is just a starting point for our discussion on the information we want to deliver for Solaris Developer and Sun Studio. If you have additional suggestions on the information you want or for how we can improve our developer documentation, please post a comment to this blog or the Solaris Developer blog.
Wednesday Feb 14, 2007
By dlindt on Feb 14, 2007
A lot of work went into the Solaris Express, Developer Edition release. A good source of information for Solaris Express, Developer Edition is at Solaris Express, Developer Edition. Links to documentation are at Solaris Express, Developer Edition Documentation Set.
While you are at it, check out the updates to the Solaris OS: Hardware Compatibility Lists, Sun Device Detection Tool page that has a link to the Sun Device Detection Tool for Solaris Express, and Hardware Certification Test Suite - Version 3.1.
We have a number of documents on docs.sun.com in the Solaris Express, Developer Edition Collections. The Solaris Express, Developer Edition Collection contains the following doc collections that are associated with Solaris Express, Developer Edition. Please note that doc collections associated with the previous Solaris Express releases are now a part of the Solaris Express, Developer Edition collections.
Solaris Express, Developer Edition
Introduction to the Solaris Development Environment [Download this Book]
Solaris Express, Developer Edition Installation Guide [Download this Book]
Solaris Express, Developer Edition Release Notes [Download this Book]
Solaris Express, Developer Edition What's New [Download this Book]
Device Driver Tutorial [Download this Book] [Buy this Book]
Linker and Libraries Guide [Download this Book] [Buy this Book]
SIP API Developer's Guide [Download this Book] [Buy this Book]
Solaris Containers: Resource Management and Solaris Zones Developer's Guide [Download this Book] [Buy this Book]
Solaris Dynamic Tracing Guide [Download this Book] [Buy this Book]
Solaris Security for Developers Guide [Download this Book] [Buy this Book]
Writing Device Drivers [Download this Book] [Buy this Book]
Solaris Tunable Parameters Reference Manual [Download this Book] [Buy this Book]
Solaris Volume Manager Administration Guide [Download this Book] [Buy this Book]
Solaris ZFS Administration Guide [Download this Book] [Buy this Book]
System Administration Guide: Advanced Administration [Download this Book] [Buy this Book]
System Administration Guide: Basic Administration [Download this Book] [Buy this Book]
System Administration Guide: Devices and File Systems [Download this Book] [Buy this Book]
System Administration Guide: IP Services [Download this Book] [Buy this Book]
System Administration Guide: Naming and Directory Services (DNS, NIS, and LDAP) [Download this Book] [Buy this Book]
System Administration Guide: Network Services [Download this Book] [Buy this Book]
System Administration Guide: Security Services [Download this Book] [Buy this Book]
System Administration Guide: Solaris Containers-Resource Management and Solaris Zones [Download this Book] [Buy this Book]
man pages section 1: User Commands [Download this Book]
man pages section 1M: System Administration Commands [Download this Book]
man pages section 2: System Calls [Download this Book]
man pages section 3: Basic Library Functions [Download this Book]
man pages section 3: Curses Library Functions [Download this Book]
man pages section 3: Extended Library Functions [Download this Book]
man pages section 3: Library Interfaces and Headers [Download this Book]
man pages section 3: Multimedia Library Functions
man pages section 3: Networking Library Functions [Download this Book]
man pages section 3: Realtime Library Functions [Download this Book]
man pages section 4: File Formats [Download this Book]
man pages section 5: Standards, Environments, and Macros [Download this Book]
man pages section 7: Device and Network Interfaces [Download this Book]
man pages section 9: DDI and DKI Driver Entry Points [Download this Book]
man pages section 9: DDI and DKI Kernel Functions [Download this Book]
man pages section 9: DDI and DKI Properties and Data Structures [Download this Book]
Compartmented Mode Workstation Labeling: Encodings Format [Download this Book] [Buy this Book]
Solaris Trusted Extensions Administrator's Procedures [Download this Book] [Buy this Book]
Solaris Trusted Extensions Developer's Guide [Download this Book] [Buy this Book]
Solaris Trusted Extensions Installation and Configuration [Download this Book] [Buy this Book]
Solaris Trusted Extensions Label Administration [Download this Book] [Buy this Book]
Solaris Trusted Extensions Reference Manual [Download this Book]
Solaris Trusted Extensions Transition Guide [Download this Book] [Buy this Book]
Solaris Trusted Extensions User's Guide [Download this Book] [Buy this Book]
Solaris Express Installation Guide: Solaris Live Upgrade and Upgrade Planning [Download this Book]
Solaris Express Installation Guide: Basic Installations [Download this Book]
Solaris Express Installation Guide: Custom JumpStart and Advanced Installations [Download this Book]
Solaris Express Installation Guide: Network-Based Installations [Download this Book]
Solaris Express Installation Guide: Planning for Installation and Upgrade [Download this Book]
Solaris Express Installation Guide: Solaris Flash Archives (Creation and Installation)
Solaris Express Package List [Download this Book]
Solaris Express Release Notes [Download this Book]
Solaris Express, Developer Edition What's New [Download this Book]
Saturday Jan 28, 2006
By dlindt on Jan 28, 2006
I attended the Silicon Valley OpenSolaris User Group meeting last Thursday, and the meeting was quite satisfying. The meeting contained a large number of knowledge nuggets, or phootons as defined by Dr. Science.
One presentation was on the Sun Studio Compilers and Tools, which you can download for free from the Sun Developer Tools page. Just sign up for the Sun Developer Network, if you are not already a member, and then download the software.
Max Bruning gave a talk on device drivers. Max teaches classes on Solaris internals, device drivers, and kernel crash dump analysis and debugging. Max has written the following articles, which covers a lot of the topics he talked about at the user group meeting:
Max talked about device trees, a simple driver, block and character devices, STREAMS, mutexes, NIC drivers, Sun Common SCSI Architecture (SCSA), Solaris USB Architecture (USBA), and many other topics.
Following the meeting, people stayed and talked for over another hour. Nice to meet people and discuss technical topics.
Sunday Jul 24, 2005
By dlindt on Jul 24, 2005
This weekend, I bought a box of dishwashing detergent from Wal-Mart. On a more interesting note, I attended a meeting of Basenji owners, went to a dog show, and took a nap because, as a co-worker once said, "Even a dog knows to sleep when its tired."
Now that I am awake, refreshed, and well-balanced, and you have some insight into me as a person, I will write about OpenSolaris docs, which was my original intent all along for this blog entry.
To have a well-organized documentation set for OpenSolaris, I think we need to look at the following points (I realize a number of points have been made in previous posts on the opensolaris.org Documentation discussion forum).
- Where to put the docs: We need an easy to locate place to
put the docs. We have models like the Documentation Page for the Solaris
hub at developers.sun.com, or
Documentation Page of the Sun Studio
Compilers and Tools hub of developers.sun.com.
We can put the docs in one place and link to them from the different communities, or we can put the docs in the different communities and link to them from the main documentation page. It doesn't matter where, so long as we don't have multiple copies of the same doc posted in different locations.
- What docs do we have: After the first week of OpenSolaris
Ginnie Wray, one of the OpenSolaris Documentation Community leaders,
had a four-page spreadsheet of different docs in
different locations. More docs are being created every day, so we need
a way to find out about the new docs and organize those docs.
I would also like to track the relevant blog entries and forum posts because a lot of valuable information is being written there.
People could notify Ginnie of new docs, but we should have a more automated process for tracking new docs.
- How to organize the docs: When we know what docs we have, we
can categorize the docs. Ginnie has an excellent suggestion with having
a documentation index like the
We could also have indexes organized by community.
We could maybe have something like what Richard (rchrd) has done for the Sun Studio hub of developers.sun.com where he has a set of topics in the right sidebar that link to pages like the Sun Studio: High Performance and Technical Computing (HPTC) page. The topics correspond to Communities, so each community could have their doc page of the references relevant to them.
- What types of docs do we want: As we start to organize the
docs, it becomes easier to determine the gaps in the docs and talk
about the types of docs we want. The index on the Gentoo site shows
patterns of various doc types, such as Guides, HowTos, and FAQs.
What types of docs do we want, and how do the docs we have fit into those categories?
- What formats, tools, and docs submission processes do we
want: For each doc type, we can determine a format and template.
Tools used might not be such an issue so long as the formats and
templates are supported. Having an easy to follow process for creating
and submitting docs could be developed from there.
The balance between ease of docs creation, consistency, formats, and process can be difficult to achieve, but it's good to set some guidelines. People can post whatever information they want in their blogs and on the forums, but having a process to take that information and present it in a more consistent manner could make it easier for people to find and use the information. It would also make it easier for people to use the information in other docs.
Going back to look at the Gentoo site, they have processes, templates, and doc guidelines.
- Gentoo docs processes at http://www.gentoo.org/proj/en/gdp/doc/doc-policy.xml
- Looks like they have a team that oversees docs at http://www.gentoo.org/proj/en/gdp/
- Some talk of their XML format at http://www.gentoo.org/ proj/en/site.xml
- Linux XML guide at http://www.gentoo.org /doc/en/xml-guide.xml
I think it would be hard to have a usable set of docs for OpenSolaris without following some guidelines.
So, these are my thoughts on organizing the docs for opensolaris.org. There have been a lot of good suggestions from people in the community, and where we go with docs depends a lot on you. Your suggestions are very much appreciated, so please stay involved and share your ideas.
Enough of this for now. Off to get pizza.
Friday Jul 22, 2005
By dlindt on Jul 22, 2005
Questions, questions, and more questions. What information do you need, where do we post that information, how do we get that information? What's really interesting about opensolaris.org is that it is and evolving community that is growing and maturing. Take documentation, or the need for information, as an example. The opensolaris.org site started with the docs resources I talked about in my June 15, 2005 blog entry.
Now on the discussion forums, we have people sharing their experiences from working with OpenSolaris, and writing about their experiences in the form of procedures and 'How Tos'. We have people wanting to write technical articles and asking how to contribute content to opensolaris.org. People need information, and they want to create that information.
We have a lot of opportunities for creating a documentation page and organizing the information people are writing. We have an OpenSolaris Community: Documentation page, but I'd really like to see a Documentation link in the left sidebar nav or a tab on the home page like on netbeans.org.
There are a lot of people writing about interesting topics in their blogs, so how do we track and organize that information? How do we make it easier to find that particular blog entry from three weeks ago? I'd still like to be able to create my own list of links to blog entries that match the topics that interest me. What else can we do with the information in all those blog entries?
As a technical communicator, watching this evolving collection of information is fascinating. Part of me wants to be able to give you all the information you need. That's what we would like to do as technical writers and information designers. But we are way past the point where we can create all the docs that you need for all the various projects and technologies we work with. Rather than diminish our value as communicators, all of this interest in creating information gives us the material we need to work with to make our docs better for you.
It's been an overworked cliche for years that people say nobody reads the docs (but they use information). Even if people avoid reading an 800-page reference manual, I'd say there is a high probability they use some of the information from that manual. That information can be in the form of smaller html files, used in technical articles or other smaller docs, any one of a number of different forms.
For opensolaris.org, we have a lot of work to do to answer those questions on how to organize all this information. Between the blogs, forums, and email aliases, you've shown the value of information and communication.
I'd like to give you the information you need in the format you need. Just keep telling us what you want for information, and we will work to improve the delivery of that information.
Wednesday Jun 22, 2005
By dlindt on Jun 22, 2005
How do we keep track of all the docs that are of interest to OpenSolaris developers? I have been talking with Sue Weber, who leads the Sun OpenSolaris docs team, and Ginnie Wray, one of the Documentation community leaders. We've been looking at the various docs that have been referenced on the various community forums, and thinking about how to create an organized list of docs or a repository for community contributed docs.
Docs that we've released with the Solaris and Sun Studio products are kept in a number of different places. I've been trying to point to various docs in some of my previous blog entries.
Today, I'd like to share some information Sun Weber provided on the Solaris Express documentation.This information was take from a posting Sue made on the Opensolarisemail@example.com and firstname.lastname@example.org forums.
Solaris Express documentation is published with each release and can be found on the docs.sun.com website at http://docs.sun.com/app/docs/prod/solaris.exp#hic
The documentation set includes 3 collections right now:
- Solaris Express Release and Installation Collection:
- Solaris Express Package List
- Solaris Express Release Notes
- What's New in Solaris Express
- Solaris Express Software Developer Collection:
- Writing Device Drivers
- Solaris Express System Administrator Collection:
- Solaris Tunable Parameters Reference Manual
- System Administration Guide: Advanced Administration
- System Administration Guide: Basic Administration
- System Administration Guide: Devices and File Systems
For each Solaris Express release, we update the "Solaris Express Release Notes" and "What's New in Solaris Express" books. Other books are regularly updated and published by Sun writers. As Solaris Express is an early access release vehicle for the next Solaris release, documentation is not always in lock-step with the code. Over time, the collections will grow as our writers work with developers to cover features that integrate through OpenSolaris.
man pages for Solaris Express are contained in the SUNWman package, which can be downloaded for installation. man pages are generally available with the same build as the code, but may at times be delayed by a build or 2.
The full set of Solaris 10 documentation is available at http://docs.sun.com/app/docs/prod/solaris.10
This documentation is not yet available as open source. For more information on the road map for OpenSolaris feature documentation, check out the Documentation community page at http://www.opensolaris.org/os/community/documentation/feature_docs/.
Friday Jun 17, 2005
By dlindt on Jun 17, 2005
Had a nice day looking at the Solaris White Album: Essential Papers listed in Ozan Yigit's blog entry dated March 4, 2005. In fact Ozan and I had talked today about the files, and he was kind enough to send me the PDF files to look at. Some PostScript files hadn't been converted to PDF yet, and some of those PostScript files had the page order reversed. I used Acrobat Distiller, included with Adobe Acrobat, to convert the PostScript files to PDF and then printed the PDF files back to another PDF file using the Reverse Pages option with the printer driver to get the page ordering right. One PostScript file failed to convert to PDF, so I looked at the PostScript file in BBEdit and found there was an email attachment embedded in the PostScript file after %%trailer. (I realize BBEdit is expensive, but there is also TextWrangler, which is free from Bare Bones Software.) I deleted the email attachment in the PostScript file, and the file converted to PDF without issue. Interesting. Spent a bit more time taking one of the Solaris White Album text files and converting it to PDF so I could make a combined PDF file of the individual White Album PDF files. I used the Header option in Acrobat to add page numbers to the combined PDF and sent it back to Ozan.
All in all, it's been a pretty good week. I've had my blog up for a week now, and the OpenSolaris site went live. I've had a chance to talk to several people about their blogs and their documentation. It really is about growing the community and adding value. Lot's of possibilities ahead.
Thursday Jun 16, 2005
By dlindt on Jun 16, 2005
Become a part of the OpenSolaris community. OpenSolaris is more than code or developer tools. OpenSolaris is a community of developers, and you can join or form the communities for the parts of OpenSolaris that interest you. I talked a bit yesterday about the Documentation community. Today I'll talk more about some of the feedback people are providing through the OpenSolaris forums.
Documentation is an interesting thing. I manage a group of writers that write docs for Solaris Developer and the Sun Studio compilers and tools.These books, along with man pages, readmes, and docs on developers.sun.com (Sun Studio Tools and Solaris hubs) and BigAdmin form part of the information resources available to you.
A lot of Solaris documentation is written by people in other groups at Sun. By being a part of the OpenSolaris community, I can tell you the docs we provide, and you can tell me the docs you provide. We learn from each other, and that is really exciting.
I just signed up for the OpenSolaris: discuss forum for general OpenSolaris comments and questions. There are a number of questions there about documentation, and a number of people are responding. There is also a documentation: discuss forum for documentation questions that hasn't been getting much activity. I am sure documentation questions will come up in other forums, so if you have a comment on docs that you would like us to look at, please subscribe to the documentation: discuss forum. We would like to talk with you.
Part of what I'd like to do is highlight some of the helpful questions and responses from some of the forums and identify the additional sources of information available to you. Some of the helpful docs mentioned from the last several days include:
- A request for a Solaris bibliography for books inside and outside of Sun. (For books published outside of Sun, it would be nice to know which books are up-to-date, or the books scheduled to be updated for Solaris 10).
- Jim Mauro has information on the Solaris Internals book in his June 15, 2005 blog entry.
- Solaris White Album: Essential Papers listed in Ozan Yigit's blog entry dated March 4, 2005.
Well this is just a start. I'll continue to let you know what I learn.
Wednesday Jun 15, 2005
By dlindt on Jun 15, 2005
OpenSolaris, code, documentation, community: they all work together. I've been reading some of the blog entries, and there is a lot of good information out there. A number of groups are working together to get you the information you need to start using OpenSolaris. The OpenSolaris Community: Documentation page is a good starting point for getting OpenSolaris documentation.
From the OpenSolaris main page, click the All Communities link in the Communities section of the left side head. The All Communities Page lists the current OpenSolaris communities, which range from Academic and Research to Zones. Some of the other communities include DTrace, Tools for the Sun Studio and GCC compilers, and Documentation.
The OpenSolaris Community: Documentation page contains links to the OpenSolaris Feature Documentation and Getting Started on OpenSolaris pages and the OpenSolaris Guide. The Getting Started on OpenSolaris page contains a table of documentation links for documents like the Solaris Dynamic Tracing Guide, Sun Studio 10: C User's Guide, and the Device Driver Tutorial.
The OpenSolaris Feature Documentation page tells you about the docs-discuss forum. You can go to the Discussions page to subscribe to the documentation: discuss forum, or one of the other OpenSolaris forums. This is your chance to get involved with OpenSolaris documentation, and we really want your comments. Building a community of people working together and sharing ideas on documentation is an exciting opportunity for all of us.
This is just a start on OpenSolaris documentation. We have many documents on docs.sun.com, developers.sun.com, and BigAdmin available for your use. I'll talk more of documentation resources in future posts.
- Introduction to Solaris Development Environment doc updated
- Getting Started with Sun Studio Software Technical Article
- Solaris Developer group blog on blogs.sun.com
- What I really learned from JavaOne ...
- Solaris Express, Developer Edition, More Than Just the Bits
- Changes in Information - Change is Change
- The Role of Information/Documentation in Product Adoption
- Documentation and Information - Lessons learned from consumer products
- Apple Final Cut Studio and the Excitement of Documentation
- Silicon Valley OpenSolaris User Group Meeting Well Worth Attending
- Adam Leventhal (dtrace)
- Alan Coopersmith
- Alan DuBoff (Solaris/OpenSolaris)
- Bryan Cantrill (dtrace)
- Charles Ditzel (NetBeans)
- Chris Quenelle (developer tools)
- Claire Giordano (OpenSolaris)
- Dan Price (Solaris)
- Dave Johnson (blogs.sun.com)
- Geertjan Wielenga (NetBeans)
- Java Tutorials Weblog (Java SE)
- Jim Grisanzio (OpenSolaris)
- John Jullion-Ceccarelli (NetBeans)
- Linda Skrocki (blogs.sun.com)
- Marc Hamilton (HPC)
- Michelle Olson (OpenSolaris)
- Richard Friedman (Sun Studio)
- Richard McDougall (Solaris/DTrace)
- Rod Evans (linker)
- Roumen Strobl (NetBeans)
- Ruud van der Pas (HPC)
- Sun HPC Watercooler (HPC)
- The Aquarium (Java EE)
- Tutorial Divas (Creator/VWP)