Friday Jun 06, 2008
Sunday Jan 27, 2008
By dlindt on Jan 27, 2008
The Getting Started with Sun Studio Software technical article is posted on docs.sun.com in the Sun Studio Technical Articles docs collection. This is the first technical article in the Sun Studio Technical Articles collection on docs.sun.com,and more articles will be added in the coming weeks.
Making Sense of Parallel Programming Terms is another technical article we have on docs.sun.com that you might find interesting.
We've been working on getting a larger variety of smaller docs on docs.sun.com. We now have the Sun Studio 12 Compiler Options document on docs.sun.com, and you can review the Sun Studio C, C++, and Fortran compiler options grouped by language or task.
In coming days, we will also have the Sun Studio readmes and Sun Studio man pages on docs.sun.com.
Why are we posting more doc types on docs.sun.com? Because we already have a solid core of documentation for Sun Studio and Solaris developers on docs.sun.com, and we want to collect more of the technical documents in one spot.
I do want to emphasize that posting technical articles or other smaller docs on docs.sun.com is not a replacement for all of the other great efforts being made to provide you with information. We have more ways to communicate with you than ever before, and a lot of people are trying new ideas all the time. The Sun Studio Wiki and the Solaris Developer Wiki are new with lots of opportunities for adding content.
I am encouraging people to participate with updating the Solaris Developer Blog
Sun Studio 12 C, C++ & Fortran Compilers and Tools and Soalris Developer Center on developers.sun.com provides great sources of information for downloading Sun Studio.
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 May 09, 2007
By dlindt on May 09, 2007
... is that it is hard to find information. Person comes up to the Sun Studio booth at JavaOne asking if the Sun Studio C compiler has a compiler option similar to an option in gcc. Well, let's look at the compiler documentation for Sun Studio 11. I know we had worked on a list of compiler options by language and platform. Go to Sun Studio 11 documentation page on developers.sun.com. Can't find the link. Use Google searching for Sun Studio compiler options on developers.sun.com, which points back to the original docs page where I couldn't find the link. It's here somewhere, let me keep looking. Meanwhile, the person who asked the question is looking on.
Another person offers to join the hunt. I know we have compiler options in the Sun Studio books on docs.sun.com. So this person starts to navigate through the convoluted path looking for the Sun Studio docs collection. Oh dear, there is no link to Sun Studio from the docs.sun.com main page. Used be a bit easier to find the Sun Studio docs. Watching the workarounds this person is following to navigate through the docs.sun.com site leaves me thinking how many workarounds have people implemented to try to get to our docs? How many people give up? How many people don't even know that we have information on these topics?
By this time, a third person steps in to say this is taking way too long. I just want to show a demo of the Performance Analyzer.
Later, I found the link to the page I was looking for (http://developers.sun.com/sunstudio/documentation/ss11/opts/index.html) through another Google search.
One theme of the JavaOne keynote was connecting everybody through devices, information, services, software. For us to do that, we need to look at the information needs of a broad range of people. How can we develop and deliver information that meets the needs of a person using a cell phone to a person using a large-scale system behind a firewall at a secure site with no internet access? If we are to be successful here, I'd like to think we at least have a handle of making it easy for people using the current devices we support to access the current information we provide. Will be some interesting discussions here.
Part of my message as we plan for these changing business needs is that it is of no value to create information people cannot find. It is of no value to have sites where you can't find the information you need. It is of no value if the information is not in a form that you can use. It is of no value if the information does not help you answer the questions you ask or help you to solve the problems you need to solve.
This is a partnership between the people within Sun and the communities we support with our information. The real value in the information we provide is realized when you can find and use that information, and that information has met your needs. Until that time, it is just a link in a list.
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 Feb 03, 2007
By dlindt on Feb 03, 2007
What are we doing now for developing technical information? What should we be doing on developing and delivering technical information? What are the changes in information needs that are affecting us that we should be responding to?
I have been looking at how to categorize some of those changes, and in the process, my thoughts on how you communicate the changes have changed. When you talk of change, it is very easy to introduce or imply value judgments. Old and new, then and now, books and technical articles, printed content and web content. It's very easy for the 'and' to be interpreted as 'versus', and that changes the meaning of the conversation. It is not that what we've done in the past is bad or no longer relevant; it is more that information needs continue to change, and we evolve with the changes.
We have the option to deliver technical content to many places now. Printed docs and docs.sun.com were two of the main options, and we now also have the option of delivering content to developers.sun.com, java.sun.com, BigAdmin, netbeans.org, java.net, opensolaris.org, blogs.sun.com, a lot of sites.
We can deliver books, retail books, online help, man pages, technical articles, tutorials, guides, blogs, podcasts, webcasts, screencasts, how to's, FAQs, forum postings. The choices keep growing, and that is part of the the excitement about the changes in how we communicate.
We can work for months on a technical document, and we can work for minutes on a blog entry, with a lot of options in between. We don't have to wait until a doc is final to get your feedback. We can post a draft and you can comment right away. We have options to work with you that we didn't have a few years ago.
Communication about change goes both ways. People talk to me about changes they want in technical information, and sometimes their message can come across as being judgmental, or the past is bad, or that some of the deliverables are no longer useful. In the end, it isn't one way or the other; past, present, or future; good or bad. It really is about what do you need for your technical information and realizing it is a mix from book to blog, article to podcast. In my opinion, it is finding the right mix of content and information types that best meets your needs for information.
Saturday Jan 27, 2007
By dlindt on Jan 27, 2007
How does information or documentation influence your decisions to download, install, and use a product? What role can tech writers/information designers play in the success of a product or a company? Is it that you download a product and then look at the documentation, or is it that we can provide you with information that influences your decision to download and use a product? Can we help to grow our user base, in addition to providing information that helps people to be productive with our products and technologies?
Growing the number of people using our products and technologies contributes to the success of a product and a company. I've been looking for ways to show a correlation between the technical information we provide and the success of a product/technology and to goals supporting the success of Sun. We've been looking at how to combine docs usage metrics with voice of the customer to get a better idea of showing how documentation contributes to product adoption.
Metrics alone doesn't tell you enough of what is going on. You can monitor docs usage trends and identify changes in trends that warrant further evaluation. Still, you need the feedback and voice of the customer to add meaning to the metrics. Conversely, voice of the customer alone isn't enough. We can have people that are very satisfied with our docs, but maybe we have only a small number of people using those docs.
How do we grow the number of people using our docs while maintaining the quality of the docs? How do we ensure we are delivering the right content in the right formats to the right locations where you can find and use that information?
When I was thinking about metrics this morning and asking myself how do we show the relationship between docs usage trends and product downloads, I realized I could ask people questions on how they use information and if information plays a part in their downloading Sun products. So here goes with a couple of questions. You can either send an email to david.lindt at sun.com or post a comment to this blog.
- Does technical information play a part in your decision to download a product?
- What technical information can we provide that motivates you to download our products and to use those products?
- What information types do you find useful? Podcasts, screencasts, webcasts, technical articles, tutorials, books, etc.
- As you start to use a product, what information types do you use?
- As a tech pubs org, where should we focus our efforts? More multimedia, more books, more shorter web docs, other?
Thanks in advance for your participation.
Saturday Oct 21, 2006
By dlindt on Oct 21, 2006
Sunday Aug 06, 2006
By dlindt on Aug 06, 2006
Finally broke down and got Apple Final Cut Studio, and my initial impressions have got me thinking enough to write a blog entry. My first impression of the product box is that it is heavy. And why is it heavy? Because the box contains books, lots and lots of books. A Getting Started Guide, a four volume User Manual, plus manuals for Motion 2, Soundtrack Pro, and DVD Studio Pro. But there is more. If you pause while looking at the books, you get the positive sensation of holding a book in your hands, of being able to turn the pages, skipping through the book without entering keywords in a search box. There is a value and excitement to a good book, and I consider a well-written piece of product documentation to be a good book.
Now don't get me wrong, before you dismiss my enjoyment of a good, hardcopy version of product documentation as being so 1990's, I am an avid proponent of delivering docs online, and delivering different types of information. It's not just about books anymore, and it's not just about content or information in any one form. It's not just about a group of tech writers that provides you with information. It's about how you participate in a related collection of information that spans groups, products, technologies, and information types. It's about working together to get you the information you need to be productive.
As we open source more of our software, more information comes from you, and we are actively trying to build communities of users who contribute content about our products and technologies. That content can be anything from a forum post, technical article, retail book (yes there is a big emphasis on writing more retail books), tutorial, how to, FAQ, Flash demo, podcast, and the whole Web 2.0 support where you will have an even greater number of options to select and organize the information that is relevant to you.
Still, I don't want to forget about the excitement of a good book, and I haven't even described my perceptions of the joy of removing the shrink wrap from a new book. Now that's another couple of paragraphs .....
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.
Wednesday Jan 25, 2006
By dlindt on Jan 25, 2006
Big day with Java Studio Creator 2 being released and available for download. Months of work, lots of energy, great results.
A lot of information is available to help you with learning and using Java Studio Creator 2.
- Java Studio Creator: Lots of content and links to information, training, support, and product downloads.
- Tutorials: For more information on the tutorials, please see the Insider Scoop From the Tutorial Divas blog.
- Online Help: An HTML version of the online help provided with the Java Studio Creator 2 IDE.
- Technical Articles: More information on Java Studio Creator 2 and AJAX and developing applications.
- Code Samples: Code and tutorials, what more could you want?
- Creator Weblogs: Lots of people are talking about the Java Studio Creator 2 release. Bob, Tor, Sandip, and the Divas are some of the people blogging about Creator.
- FAQs: A growing list of Java Studio Creator 2 topics.
Lots of content to get you started. So please download Java Studio Creator 2, and give the product a try.
Please submit tutorial feedback and requests to: CreatorDocsFeedback@Sun.Com Please let us know of your suggestions and ideas on how we can improve the Java Studio Creator 2 documentation.
Friday Dec 16, 2005
By dlindt on Dec 16, 2005
Fame, recognition, divas, creativity, enthusiasm, Google, and Java Studio Creator. Part of the satisfaction of working at Sun is being able to work with a good team of imaginative and talented people. For example, typing "Tutorial Divas" in Google shows the first link in the search results as Insider Scoop From the Tutorial Divas. Gail and Chris talk about the tutorials for Java Studio Creator, where tutorials are one of the primary doc deliverables for Java Studio Creator. The tutorials team has been doing a great job of providing a wide variety of tutorials on Java Studio Creator, and if you haven't had a chance to explore the tutorials, please do so.
After all, it isn't every day that you get to view the work of real, live "Tutorials Divas", which is a title supported by Google.
Thursday Dec 15, 2005
By dlindt on Dec 15, 2005
A new SDN Developer Channel on The Future of Multicore Computing is available on developers.sun.com. SDN Channels are monthly themes on tools and technologies. Of particular interest is the 15-minute video on high performance computing with contributions from Richard McDougall, Bryan Cantrill, Lawrence Crowl, and Nicolai Kosche.
Wednesday Dec 14, 2005
By dlindt on Dec 14, 2005
Information. It's all around you, it's useful, and it's fun. Increasing your awareness of useful information is a good thing, and I am pleased to say that my value add for the day is to let you know of the new Chip Multithreading (CMT) page on the Sun Studio Tools hub of developers.sun.com.
The CMT page contains links to a variety of topics on Throughput Computing, OpenMP, MPI, and Sun Studio tools for parallel computing. Lots of great content, guaranteed to enhance your productivity and increase your satisfaction level.
Just to wrap up this blog entry, I'd encourage you to spend some time browsing the content on developers.sun.com. developers.sun.com is the greatest thing since toaster ovens, so check out the content today.
Saturday Aug 27, 2005
By dlindt on Aug 27, 2005
I realize it been almost a month since my last blog entry, so I really need to channel a few calories into the ol' blog and resuscitate this beast. It's not that I haven't been thinking this last month; I've been thinking a lot. I just haven't been thinking about channeling my thoughts into a public forum. It's not even that I've been thinking of anything that is all that confidential; just too many rough edges on the thoughts to make interesting.
Part of what I've been working on this last month is developing proposed training plans for some of our developer products. Training classes for creating Rich Client applications with NetBeans IDE. We have some Rich Client information in the NetBeans IDE Field Guide, and we would like to do more to highlight the value of using NetBeans IDE, NetBeans Platform, and the Desktop Java APIs.
I am also working on proposed training plans for Solaris Developers, people who develop applications for Solaris or who will be modifying OpenSolaris. Here we are looking at a set of classes that would help Windows and Linux developers to port their applications to Solaris, or to give developers new to Solaris enough information to get started with modifying and extending OpenSolaris. Writing portable code; optimizing application performance on Solaris; compile, edit, debug, analyze program performance with Sun Studio 10 (marketing info, developer documentation), writing device drivers, and working in a mixed native C, C++, Fortran and Java code environment. Lot of interesting points to ponder.
Earlier this month, I did Sun Studio booth duty at LinuxWorld, and this was a really exciting event for us. We have alpha versions of the C and Fortran compilers for Linux. The C++ engineering team is also working on the Linux version of the C++ compiler. Nice to get the preview versions of the compilers out in time for LinuxWorld. There was also a lot of good interaction between the people at the Sun Studio, OpenSolaris, and the Ultra 20 booths. What is really exciting (I am trying to avoid saying way cool) about the Ultra 20 is that it comes with fully licensed versions of the developer tools.
Part of being a manager is recognizing the value of the people in your org and the value of their contributions. We are really looking at how developer documentation can help you to efficiently use the product. For Java Studio Creator, we have a tutorials team that has been doing a tremendous job of writing Java Studio Creator tutorials and an online help team where we now have the online help on developers.sun.com (this is a web-based version of the online help provided with the Java Studio Creator product). Most of the tutorials were previously available as locked content where you needed to pay for a SDN subscription, but a lot of the tutorials are now provided for free, and we are working on getting the online help unlocked.
I will continue to highlight the doc and information contributions people are making for other products in future blogs. For now, I've run out of thoughts, and I need to save something to write about for tomorrow's entry. The siren song of Peet's coffee calls. I have also found that adding several scoops of Double Rainbow French Vanilla to my espresso is a very cost-effective, efficient, and labor-saving way of getting the satisfaction of some of the higher-priced coffee beverage products, and I don't even have to sully the blender.
Sunday Jul 31, 2005
By dlindt on Jul 31, 2005
Haven't quite made the trek yet to the espresso maker, so I've been having a lazy Sunday morning browsing the different blogs looking to see what makes me open my eyes a bit.
I really like what the BBC is doing with RSS feeds, like their front page RSS feed, and their use of RSS feeds for topics. Macromedia also has an interesting list of feeds, and you can customize the list or create an RSS feed based on Search Terms. Could we set up some pages on a Docs page on opensolaris.org where we have updated lists of blog entries or a page showing blog entries grouped by community or topic? We could also try this for pages on developers.sun.com where we have RSS feeds for the technical articles for the various hubs?
I've been using Sage as an RSS Reader, and I really like it. Sage lets me know when various blogs and web sites have been updated, but I still have to look at all the updates to see what is interesting to me. I'd like an RSS feed that shows me all the postings on netbeans or dtrace. Doing a Google search on "site:=blogs.sun.com dtrace" helps, but I'd still like the results displayed in an RSS reader. Technorati helps with searching on topics like netbeans modules, but without an agreed upon set of metadata, the search results aren't as focused as I would like.
We are getting the content, but it is a lot of isolated and random topics. For us to really use this information, we need to do more to aggregate the information.
Enough thinking for now. Downstairs to coffee (Peet's Italian Roast).
Saturday Jul 30, 2005
By dlindt on Jul 30, 2005
I should wait to post this until tomorrow where I could say I have written my entry for the day, but I can't contain my excitement. Upon looking at the Referers stats for the number of page hits, I see today that only 3% of the hits are from gambling, credit, and other sites. On other days, the number of hits from the spam bots is closer to 25%. Sort of dampens my enthusiasm to watch my page hits creeping up, only to realize my popularity is due to sites that want me to gamble or refinance my house.
Now that I realize I am totaly out of balance, like what am I doing looking at my page stats on a Saturday night, I really have to leave to have some quality, quadrant IV vegetative TV time.
By dlindt on Jul 30, 2005
When asked about my career goals, my first response is to stay relevant. My second response is to be in a job position where I can participate in the discussions that affect us as an org or as a profession (in this case, technical communications). This last week has been spent looking at the FY06 goals and thinking of how we adapt to meet those goals. Part of that effort involves mapping the descriptions of what we do as technical communicators to the terminology of the goals and looking for ways to show how we can be relevant to achieving those goals.
We've had discussions about internal customers and external customers. As technical communicators, it is easy to see that we have external customers, who are the developers or sys admins that use our documentation deliverables. We also have internal customers, such as the VP who wants more training or the engineering director who wants smaller, web-based docs. Our ability to get funding and support depends on our ability to meet the needs of the internal customers. Our value as a profession depends on our ability to support our external customers with accurate information in a format they can use. How to maximize the satisfaction of both the internal and external customers is the challenge.
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 Jul 20, 2005
By dlindt on Jul 20, 2005
Tuesday Jul 19, 2005
By dlindt on Jul 19, 2005
What does it take to make an interesting blog? Do you view blogs more as a source of technical information, a diary, a collection of personal thoughts, or all of the above?
I guess this blog is more a reflection of my interests at the time that I care to express them in a public forum. Right now, I am more interested in how we present information and what we can do to make it easier to give you the information you need.
How do we give you the information you need? First we have to figure out what you need. We've had surveys, talked to developers, talked with people in other groups within Sun, had weekly meetings about different things people are doing with web-based informations or various web sites supported by Sun. Lots of ideas, but no single answer.
Without a clear answer to what information do you need, then how do we proceed? Do we keep doing what we've done for docs five years ago or do we do something new? To do something new, we need to cut back on doing some things we've done in the past. Do we do more with technical articles or blog entries and less with manuals or online help? Do you want smaller docs or pieces of information or do you want larger books? Do we focus more on training or providing reference material?
We talked at lunch today about being flexible, but the word of choice now is to be adaptable. You've changed the way you work with information over the years with Google, smaller docs, and blogs, and as technical communicators, we need to adapt to those changes. Five years ago, we focused on books, man pages, and online help provided with the product bits. You still need a lot of that information, but now we have many different ways to deliver that information.
I'm willing to try some different things with docs, and to take some risks with how we give you information. If we cut back on something, and that is an issue, let us know through the Documentation Feedback page. Positive feedback on the information you like is also welcomed. We will focus more on what you need.
We do monitor the doc feedback aliases, and we do respond to your comments. I would really like to hear your opinions.
Tuesday Jul 12, 2005
Thursday Jul 07, 2005
By dlindt on Jul 07, 2005
After installing Sage, you can right-click on an RSS feed icon, select "Bookmark This Link...", and then add the feed to the Firefox Bookmarks ->Sage Feeds menu. Another way to select a feed is to display Sage in the Firefox left sidebar, display a page in Firefox that contains links to RSS feeds, and then click the Discover Feeds icon (the Magnifying Glass icon). Sage displays a list of site feeds, and you can add the feeds to the Sage window.
A screenshot of Sage in Firefox is shown below.
Tuesday Jul 05, 2005
Monday Jul 04, 2005
By dlindt on Jul 04, 2005
From the June, 2005 blogs.sun.com usage statistics, 49% of the visitors by country are from the United States. The United Kingdom and Canada accounts for another 12% of the visitors. Rest of world accounts for the remaining 39% of visitors by country. Roughly 1/3 of the people come to blogs.sun.com using a search engine, another 1/3 come from other web sites, and the other most common method is to type the URL or use a bookmark.
I'd be curious about how these usage statistics compare to www.sun.com or developers.sun.com. How effective are we at communicating through blogs.sun.com, and how can we promote visibility of the site and communicate more effectively with developers in other countries?
I've had some discussions with people in other groups on whether blogging is effective communication, and on how we can organize and track the information in the blogs. Making the information more accessible to non-native English speakers, agreeing on a consistent set of content tags for some of the more popular topics, continuing to encourage communication and linkage between bloggers, growing the product communities, lots can be done.
We've given a lot of attention to blogs.sun.com at Sun over the last few months. A number of people who started blogs will do a few entries and that will be it. Others will continue blogging and capitalize on the benefits to blogging.
The success of our products and the willingness of developers to use our products is due in part to the quality of information describing our products and technologies. Information comes in many forms and from many people, not just tech pubs. As technical communicators, we need to show how we fit into an information model with multiple sources of information, formats, contributors, and points of access. The blogs are an opportunity to tell people what we do at Sun, how we contribute, and how we can help to make it easier to get information to developers.
Saturday Jul 02, 2005
By dlindt on Jul 02, 2005
Jonathan was one of the speakers at the blogs.sun.com user group meeting on the Sun Menlo Park campus last Thursday (June 30). Claire Giordano also talked about the role of blogging with the OpenSolaris launch on June 14.
Jonathan talked about extending the reach of communication with blogging, being able to communicate more directly with people without going through channels, and showing that Sun is an interesting place to work with interesting people working on interesting products. Entries talking about Sun culture, tools, and new bloggers catch his eye. Jonathan encouraged people to talk in an authentic voice, not a corporate voice.
Voice in blogs is an interesting point. I think it takes some time to find your voice. We are communicating in a public forum, and we really don't know the extent of our reach. Voice can range from the one extreme of saying things that probably shouldn't be said to anybody to the sterile corporate talk that people dismiss as disengenuous hype. Voice for me falls somewhere in between, and I'm trying to figure it out. You still need to communicate effectively, whether the communication occurs in a blog or at a project meeting.
Thursday Jun 30, 2005
By dlindt on Jun 30, 2005
JavaOne is over, but I didn't write a thing. Getting home at midnight the last few nights, I'd think "Do I want to write a blog entry?", and I'd think "No, maybe tomorrow." I worked the show floor for three days, so I didn't get a chance to hear any keynotes or presentations, and I felt a little behind the times when people would ask about some of the interesting announcements.
Still, this was a great three days to talk to developers and to meet Sun employees from all over the world. So many voices on the phone, it's really nice to finally meet people face to face. During one conversation, the person said they needed to talk to David Lindt about something, and I thought for a moment, gee that's me. Turned out to be a very productive conversation since we were all there, including me.
The booth layout for JavaOne was really nice. Clusters of four groups, and we had Sun Studio 10, NetBeans 4.1, Java Studio Creator, and Java Studio Enterprise in our cluster. Thsi made it really easy to send developers to the right booth. It was also nice to see the people from Prague at the NetBeans booth, which was right next to our booth.
One of the more interesting conversations I had was with the people at the Global Education booth. We got to talking about how computer science and engineering students learn about developer products, and how we can get more information to students. The SDN Student Developer Program tells about resources for students, internet gamers, and researchers.
Busy couple of days, and I need to think about what we learned from talking to the developers that stopped by the Sun Studio booth. JavaOne isn't the main show for a product containing the C, C++, and Fortran compilers, but we found a number of people that needed to call legacy C and Fortran codes from Java apps. There is a connection between the languages, and we just need to communicate the relationships between the products and languages. A lot of times, it's easy to get into this debate of Java versus native languages, but it doesn't have to be either or. Developers use Java, C, C++, or Fortran, based on their requirements. Where it makes sense to use Java, then use Java. Where it makes sense to use C++, then use C++. Lot of important legacy Fortran apps out there, so don't write off Fortran yet. As technical communicators, we need to give you the information you need to do your job efficiently and with the right languages and tools.
Sunday Jun 26, 2005
By dlindt on Jun 26, 2005
More than 500 people attended NetBeans Day 2005, filling the conference room to capacity.
James presented. The room was packed, and people were standing against the walls. It was really exciting to see the turnout. More than 500 people (I'll get the final numbers later) listening to NetBeans presentations on a Sunday afternoon.
Jonathan talked about building developer communities.
300 copies of the NetBeans IDE Field Guide were given to the first 300 attendees that picked up their name badges. I am really excited about this book. This book is current for NetBeans 4.1, and it is nice to get another NetBeans book into the retail channels.
The book signing at the reception following the presentations was a success. From left to right: Christopher Webster, Charlie Hunt, Patrick Keegan, and Ludovic Champenois. This book was a real team effort, and I want to thank Patrick, Ludo, Charlie, Chris, and Gregory Crawley for their efforts. Everybody had day jobs, but they took their time to contribute the content, and they worked as a team to make the book happen in time for JavaOne. Thanks again for your hard work.
- 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)