Docs-Discuss Gang,
I had offered to summarize the discussion from our community meeting.
Here's my summary:
Barbara
Summary Points from OpenSolaris Docs-Discuss Community Meeting 5/21/08
Prior OpenSolaris documentation roadmap was about the process of getting
docs into the open. This roadmap has largely been accomplished. We have
moved source outside (tarballs for S10 material, mercurial
repositories...). We need a new roadmap for content going forward. Alan
will own the roadmap. Priorities for new roadmap are as follows:
1 - Encourage community contributions - Setup content management
solutions that lower barriers to community contributions both for
creating and reviewing docs
1a. Solutions must include community-usable tools chain for document
creation and conversion to needed formats
- i.e. Generate .pdf from tarballs
- i.e. Community able to generate d.s.c.-style documents
Action Item: Ben help troubleshoot Rainer's script for conversion of
tarballs to .pdf
Action Item in progress: A Docstools person is working on SGML to
HTML conversion
Action Item: Setup Tools Chain project, Ben and Ranier co-lead -
Project will evaluate current tools chain and determine next steps for
open source tools chain
- i.e. Barbara and others have prototyped mercurial repository tool
Action Item: Wenling help test tools for non-English content
1b. Setup OpenSolaris wiki for documentation
- i.e. cookbook with recipes model
- i.e. Fedora model
i. wiki must consolidate scattered docs material (genunix, bigadmin...)
ii. wiki must provide single point of entry
iii. wiki must provide easy navigation to where user wants to go
iv. wiki cannot be the only source for documentation. But, use wiki
as primary
location for document creation and revision. Then, for example, push the
changes to the
main document periodically (every few months), where it can be
navigated, searched...
v. wiki must provide relevant, accurate and timely information.
1c. Lower stylistic barriers to contributions to traditional
documentation (manuals and man pages)
i.e. Take an existing chapter, create it as a wiki page, enable
community to modify the wiki page, convert it back to XML, and
create/edit/append to original document.
1d. Make documents available for review by docs-discuss community
i. Review cycle needs to be communicated to docs-discuss community
prior to review
ii. Include docs-discuss alias in review discussions
iii. Setup general procedure where all documentation moving through
the pipeline would be on a review page, so that community can see what's
in the works, what review is wanted, what the deadlines are.
i.e. There is an existing "Docs for Review" page in OpenSolaris docs
community.
iv. Even if document covers software that is not yet released,
community still wants to provide feedback, such as editorial feedback.
Community may choose to investigate the project further, based on document.
v. Have feedback button link to the docs-discuss alias? Feedback is
a bug for
docs-discuss community. Strip names from feedback prior to routing to
alias for privacy?
1e. Community must discuss further which document formats are best and
how to implement:
- Plugins can convert wiki format into HTML or .pdf.
- Do we need to convert wiki material into XML? XML is a more robust
and better structured tool than HTML. You can include flowcharts,
graphics, and navigate through XML. But XML is more difficult for
community to manage. Can XML be used as part of the tools chain?
2 - Maintain ongoing communication internal/external in order to align
community docs efforts and Sun-internal docs efforts.
i. Make OpenSolaris style guide more in line with Sun style.
ii. Continue with monthly docs-discuss team meetings.
3 - Balance internal docs with community-driven docs -
i. The traditional documentation manuals continue to be very
important. Everything else (blogs, wikis) is supplemental to the main
manuals.
ii. Lower barriers to contribution, but maintain ability to produce
quality documentation that is deliverable in various formats.
4 - Fill gaps in OpenSolaris documentation based on community requests
- What's New
- Screencast about how to configure the Network Stack (Ben might tackle)
- Expand Application Developer's Guide to cover IPS
- Provide short, targetted "getting started" articles, such as how
to setup desktop, mail service...all the sys admin tasks
5 - Everything should be done in the open, both work by Sun writers and
community contributors.
i.e. If book is in the open, in a repository, community can access
and contribute to the book. Not all community people will want to learn
the tools chain to do this.
6 - Consider and determine document attribution policies for OpenSolaris
documents,both
for Sun-internal contributors and community contributors.
Meeting discussion points:
- too many Sun internal contributors (prior writers, SMIs) - logistical
nightmare
- SCA on file is the legal process currently
- note in change log or in XML comment?
- what is contribution threshold for attribution?
- Add attribution section in preface to document?
- required for external contributers
- can policy vary for Sun-internal and external?
- handle via wikis - disallow anonymous changes?
- How granular? document owner or more specific?
