|
Replies:
7
-
Last Post:
Dec 19, 2005 7:51 PM
by: michelle
|
|
|
Posts:
1,674
From:
Registered:
7/15/05
|
|
|
|
Which tools does Sun use for docs.sun.com?
Posted:
Aug 12, 2005 6:03 AM
|
|
The subject says it all. I'm at the point where I need to generate some documentation, and I'd like to generate it in a consistent, typographic manner.
I like the consistent layout of Sun's documentation on docs.sun.com, and I'd like to know which tools are used to generate the HTML and PDF documentation.
|
|
|
Posts:
70
From:
Menlo Park, California
Registered:
4/27/05
|
|
|
|
Re: Which tools does Sun use for docs.sun.com?
Posted:
Aug 17, 2005 3:45 PM
in response to: ux-admin
|
|
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.
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?
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?
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.
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.
Thanks,
Sue
Sue Weber, Program Manager-Solaris Documentation
Nevada, Express, Trusted and OpenSolaris
(650) 786-5467 x85467
susan.weber@sun.com
|
|
|
|
|
Posts:
165
From:
US
Registered:
6/14/05
|
|
|
|
Re: Which tools does Sun use for docs.sun.com?
Posted:
Sep 9, 2005 9:00 AM
in response to: sweber
|
|
> 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@sun.com
|
|
|
|
|
Posts:
1,674
From:
Registered:
7/15/05
|
|
|
|
Re: Which tools does Sun use for docs.sun.com?
Posted:
Nov 2, 2005 6:18 AM
in response to: tjyang
|
|
> my requirements
>
> 1. Use opensource documentation tools.
> increase the doc tool avaiability to the
> the community.
Why? The focus is on generating documentation, if it enables one to do the job, what difference does it make if it's OpenSource or not?
Those who write documentation don't generally constantly hack away at the tools -- that's usually done only at the beginning to set up the infrastructure. But in this case, the infrastructure has already been set up for you, meaning you can focus on writing documentation.
> 3. Have standard templates for documenations.
> So the efforts can be spend in the content not
> not the layout.
Agreed. The focus should be on the content, and the tools should worry about the layout.
|
|
|
|
|
Posts:
165
From:
US
Registered:
6/14/05
|
|
|
|
Re: Which tools does Sun use for docs.sun.com?
Posted:
Dec 9, 2005 9:57 AM
in response to: ux-admin
|
|
> > my requirements
> >
> > 1. Use opensource documentation tools.
> > increase the doc tool avaiability to the
> > the community.
>
> Why? The focus is on generating documentation, if it
> enables one to do the job, what difference does it
> make if it's OpenSource or not?
I should have said, freely available documentation tools instead of opensourced ones.
Asking docs contributors to purchase documentation tool in order to contribute OpenSolaris documents for free doesn't make sense (to me at least).
> Those who write documentation don't generally
> constantly hack away at the tools -- that's usually
> done only at the beginning to set up the
> infrastructure. But in this case, the infrastructure
> has already been set up for you, meaning you can
> focus on writing documentation.
>
> > 3. Have standard templates for documenations.
> > So the efforts can be spend in the content not
> > not the layout.
>
> Agreed. The focus should be on the content, and the
> tools should worry about the layout.
|
|
|
|
|
Posts:
1,674
From:
Registered:
7/15/05
|
|
|
|
Re: Which tools does Sun use for docs.sun.com?
Posted:
Nov 2, 2005 5:52 AM
in response to: sweber
|
|
> 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.
Thanks! :)
> 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.
If it's not too much to ask, what is used to "churn out" the XML pages into HTML that we see in the web browser (i.e. Apache with mod_xml & mod_xslt, etc.)?
> 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.
Personally, I wouldn't mind the "Sun-centric" approach at all.
> 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?
Interchange of documentation is not exactly a concern for me at this point: as of right now, I write my documentation in OpenOffice.org 1.1.4 using document templates and styles (some of which I customized/defined in the template) and generate a PDF.
I believe that, unless you have to write/edit documentation, PDF is good enough as a target. HTML is OK too, so long as it's W3C standards compliant.
> 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?
It's my belief that the focus should be on consistency of content, because in the end, it boils down to making it easy and efficient to read and understand -- consummate the content of the documentation.
Having written that, some people may want to go lower than the documentation editor, so having source code which is easily understandable/readable/editable in a plain ASCII editor sure couldn't hurt.
> o Are you looking for processes, rules, guidelines?
Absolutely! Processes, rules and guidelines are essential to any engineering process; without them, there can really be no engineering.
> o Are you looking for consistent templates for
> different kinds of
> documentation? (books, articles, how-tos, online
> help, man pages, and
> the like)
Yes! One of the focal points is consistency, because inconsistent layout between documents (for example, between one book and another) can only confuse the reader. Besides, lack of consistency directly impacts the quality of the product, which is in this case information.
BTW, I'm not necessarily sold on the pitch that everything must be open sourced to make it worthwhile.
Technically speaking, it's completely irrelevant to me whether the tools I use are open source or not -- so long as they are freely/readily available.
My concern with documentation and documentation tools is product delivery and productivity, not ideology.
|
|
|
|
|
Posts:
1
From:
Las Cruces New Mexico
Registered:
12/9/05
|
|
|
|
Re: Which tools does Sun use for docs.sun.com?
Posted:
Dec 9, 2005 8:46 AM
in response to: ux-admin
|
|
Well..you can create or modify SGML files by hand in an editor. Back in the day at DEC that was all we had. Of course creating our ADEPT template for Open Office and have Office be able to spit out xml might work.
|
|
|
|
|
Posts:
1,271
From:
US
Registered:
10/6/05
|
|
|
|
Re: Which tools does Sun use for docs.sun.com?
Posted:
Dec 19, 2005 7:51 PM
in response to: markob
|
|
Hi all,
I've read through some of the proposals for collaboration and I think its awesome how much energy and interest we have in this community, so I want to enable it to be unleashed and get some great projects going around docs for new technologies that are appearing in OpenSolaris. [insert pompoms here]
I know some folks want Solbook, but it requires an expensive editor (Epic) and part of the goal is to keep barriers to entry low as possible. We use a command to publish our SGML source as XML for docs.sun.com--I don't know much more than that, because I don't have to. The output is a single .book file with size about 500K for a 200 pg book. So, we could potentially open source the .book file for the doc community in order to do collaborative work. Community members could use any editor they choose and use the DocBook DTD to check validity. Thoughts?
For the publishing of the .book files, HTML is the most reasonable output I can figure. We could just link in a style sheet or get a bit more sophisticated with an XSLT script to transform to HTML. Thoughts?
We could provide Solbook templates for doc community use and publish new documents in HTML on the doc community pages. Use of the templates, when we get them created, would not be required and we can accept any formats for *new documentation. [insert open invitation to send us stuff here] Thoughts?
For *existing documentation that is published on docs.sun.com, we have more process steps:
1-formal request for a sponsor, sent to request-sponsor at opensolaris dot org (I now see that we don't outline how to complete this step on our How To Participate page, so I will add that tomorrow).
2-signed, returned Sun Contributor Agreement
3-adherance to the published style guidelines, term guidelines, and DocBook rules
4-participation in technical and editorial reviews
5-TBD for the unforseen :)
This strawman outline of a plan gets us a way to collaborate on existing docs (XML) or create new docs using SGML/other format and publish with HTML. There are still several issues that need to be overcome (source control, linking, workspace locations and management), but I wanted to post this outline in response to the 'most viewed' docs-discuss thread, since I haven't responded yet, but I am starting to get a vision of how we can all work together.
Let me know what you think, if there are requirements I've missed or other things we'll need.
Thanks,
Michelle
OpenSolaris Doc Community
|
|
|
|
|
