> These are great questions. We've been reluctant to
> present the "Sun
> story" on documentation tools as we try to develop a
> community strategy.
> Nonetheless, you asked, so we'll give you some
> details.
>
> Sun's Solaris writers author in sgml. We have an
> internal DTD, Solbook,
> which is based on DocBook. It is a subset of
> Docbook, that is, we have
> removed many elements and attributes that we found
> were unnecessary to
> the documentation model and templates that we use.
>
> We then process the sgml source to generate XML, html
> and pdf. The XML
> and pdf are published to docs.sun.com. html and pdf
> were included on
> documentation media for Solaris 10.
>
> The tools we use to generate the XML, html and pdf
> were internally
> developed based on commercial products-- a problem in
> an open source world.
>
> Style-wise, we have a Sun Editorial Style Guide.
> Most of it has been
> published as "Read Me First! A Style Guide for the
> Computer Industry"
> We also have an sgml style guide. We envision
> putting out "lighter"
> versions of these books that are not so Sun-centric.
>
> Right now we are trying to figure out how we can
> scale all this for an
> open source community. Yes, we'd like to influence
> the community toward
> an sgml/xml model. At the same time, we recognize
> that we can't just
> impose our model, as we believe it cannot be fully
> supported with open
> source tools.
Personally, I like Docbook SGML/XML over LaTeX becuase
the syntax is easier. Also the tool itself need to be freely
avaiable to the doc community.
>
> What we need to know from you and others in the
> community are what your
> priorities are.
>
> o Is it important to be working in a consistent
> format and style? This
> allows for easier interchange of documentation?
Yes. This is vital to have a consistent format.
> o Does the format the documentation is authored in
> matter? Rather,do we
> sacrifice interchange and focus instead on setting
> the standards in the
> areas of editorial and style guidelines and
> technical content? For
> example, we set rules on how something should look,
> how it should be
> reviewed, and output format that we post, but we pay
> less attention to
> how you got there?
In short can we just learn from Linux Documenatation Project (LDP) ?
>
> o Are you looking for processes, rules, guidelines?
> We envision a doc
> project site managed by our community leaders. Each
> project or piece of
> documentation would have an owner who would manage
> the contributions to
> that project or documentation. For open source
> documentation that
> originated within Sun, we would regularly update it
> with contributions
> from the community and from within our Sun writing
> staff. The community
> would be able to post to the site through the
> community manager, as well
> as download open source documentation.
This process should be aumotated by scripts as much
as possible.
> o Are you looking for consistent templates for
> different kinds of
> documentation? (books, articles, how-tos, online
> help, man pages, and
> the like)
>
> Our roadmap is posted within the documentation
> community site. We anticipate
> some changes in emphasis based on community input,
> and we hope to flesh out
> more details to post for you very soon. We encourage
> feedback so that we can
> better understand your needs and requirements.
my requirements
1. Use opensource documentation tools.
increase the doc tool avaiability to the community.
2. Can be updated by either vi or emacs.
So slow GUI editing is not required.
3. Have standard templates for documenations.
So the efforts can be spend in the content not the layout.
tj
> Thanks,
>
> Sue
>
> Sue Weber, Program Manager-Solaris Documentation
> Nevada, Express, Trusted and OpenSolaris
> (650) 786-5467 x85467
> susan.weber at sun.com
This message posted from opensolaris.org
