Sunday July 24, 2005

More on OpenSolaris docs

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 for the 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 going live, 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 www.gentoo.org site. 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.

Technorati tags: OpenSolaris