We need a top-level link to a Documentation page from the top-level opensolaris.org page.
I don't think of Documentation Community as the site for OpenSolaris documentation. I think of the Documentation Community as the people interested in defining the structure of the docs on opensolaris.org, the types of docs we have or can provide, the processes for submitting those docs, and the organization of those docs on opensolaris.org. 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). - [b]Where to put the docs[/b]: 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 http://developers.sun.com/prodtech/solaris/reference/docs/index.html , or for the Sun Studio hub of developers.sun.com at http://developers.sun.com/prodtech/cc/reference/docs/index.html. 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. - [b]What docs do we have[/b]: After the first week of OpenSolaris going live, Ginnie 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. - [b]How to organize the docs[/b]: What we know what we have, we can categorize the docs. Ginnie has an excellent suggestion with having an index like the Gentoo site (http://www.gentoo.org/doc/en/list.xml). We could also have indexes organized by community. We could maybe have something like what Richard has done for the Sun Studio hub of developers.sun.com where he has a set of topics in the right sidebar (http://developers.sun.com/prodtech/cc/reference/docs/index.html) that link to pages like the HPTC page at http://developers.sun.com/prodtech/cc/hptc_index.html. The topics correspond to Communities, so each community could have their doc page of the references relevant to them. - [b]What types of docs do we want[/b]: 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? - [b]What formats, tools, and docs submission processes do we want[/b]: 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. This message posted from opensolaris.org
