Hi,
Apologies for the lengthy mail, I was sort of doing a brain dump on
doc.oo.o structure and would appreciate comments.
Generally, I think everybody's in agreement to separate the user space
from the contributor space for the doc project.
If you aren't, scream now!
The user space will be for presenting the documentation to focus on
usability and searchability. The docs for the latest OOo version
should be made readily available. I suggest that we strive for offering
the documents both as online and offline version, i.e. having an ODF
(and/or PDF,) and a HTML version available, which would then be
searchable using the collab.net search facilities (which IMO
leave room for improvement).
We should, of course, not forget to encourage users to also look on
the contributors pages. We could, for example, present a list of
light tasks for each documents that users could choose to help
out with. And also, the online versions should allow instant
feedback and should allow some sort of commenting.
It's so important to just get people's opinion on the docs,
even if it's just a "I like it" or "I hate it".
The contributor space will focus on collaborative and administrative
stuff instead of the presentation, e.g. list of document owners,
doc status, doc issues, doc plans, doc source code, etc
The ideal place for the contributor space is the wiki since it
fosters collaboration and has a minimal entry barrier for any type
of contribution. The doc.oo.o web pages would be mainly used
for publishing the final bits.
However, there will be documentation types that will also reside
on the wiki and the user and contributor representation are the
same. This is no issue if the granularity of the doc type
allows the administrative overhead to be kept small. Typically, this
includes FAQs and How Tos.
We (Sun) are currently in the process of open sourcing the
Developers Guide and plan to have it maintained through the
wiki also. This may be a viable way for many future collaboration
even for some books that are now maintained as ODF. We would have
some mechanism that allows us to collect pages from the wiki and export
them as ODF (or PDF) to publish as a book.
I understand, though, that not all documentation types are suited for
wiki publications but I'd be curious to find out where the complexity of
docs makes it unfeasible to use a wiki. The DevGuide may be a good
guinea-pig for that.
Now here is what I think the main web page should offer as a
landing page for both users and contributors:
Send users to the "static" web pages where the final versions
(or current drafts) of the documents are available, both as
ODF (PDF) and HTML. Include a request for contribution and
feedback (this can be directed to the wiki, then, where we'd
have a feedback/discussion area for the documents.
For granular and more dynamic document types, like FAQs and
(possibly) Howtos, send the users to the corresponding wiki pages.
Sen contributors to the wiki pages that allow better collaboration. We'd
set up a structure that represents how the docs are organized,
using Categories as labels, e.g.:
Category:Documentation
Page Dashboard (project overview for contributors)
Category:Manuals
Page User Manual
Page Setup Guide
Page Administration Guide
Page WhateverOtherGuidesThereWillBe
Category:How Tos
Page General
Page Writer
Page Calc
Page Draw
Page Impress
Page Database
Page Basic and Macros
Page Installation and Setup
Category:FAQs
Page General
Page Installation
Page Writer
Page Calc
Page Draw
Page Impress
Page Formula
Page Database
Page Troubleshooting
Category:Developer Documentation
Category Developers Guide
Many Pages below this one
Page BASIC Guide
Category:Online Help
Category:Samples and Templates
Category:Tutorials
Something like that. The current category hierarchy on the wiki is
Category:Documentation
Category:Macros
2 Pages
Category:OnlineHelp
15 Pages
Category:User FAQ
5 Pages
Category:Writer
10 Pages
So it wold need a little tweaking but the basic structure
is there already. There is also more docs spread out on the
wiki but not categorized properly.
The next steps on this path would be as follows:
1 Finalize doc.oo.o main page with new structure
2 Create wiki hierarchy and populate main pages for categories
3 Go through the wiki and collect docs not yet in the
Documentation category
4 Clean up web pages to present published guides only
5 For the wiki implement some sort of editorial process
to ensure that the content is not outdated
6 Implement and document a process of providing guides as
ODF/PDF (offline) and HTML (online)
7 Implement a mechanism to collect feedback for HTML
online documentation (in contrast to wikis documentation)
I'd be happy to go ahead with 1 and 2, and would appreciate
any help with the other steps as we go along (*if* we should
go ahead, that is).
For 5 and 6, I am confident that we from Sun can
help out there.
Last not least:
8 Discuss with native lang leads how non-English
contributions could be leveraged
I'll be off for a couple of weeks starting next Tuesday
(my second daughter is due next week ;-) so forgive me if
I don't respond timely.
Thanks
Frank
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
