Jerome Louvel wrote:
Hi Marc,
This looks pretty good! Would it be possible to have a Daisy hosting
for the wiki.restlet.org domain? If so, we could migrate the current
Restlet wiki which is hosted on java.net and leverage the Daisy book
publishing feature.
I'm also planning to migrate from Tigris.org to Trac (when its 0.11
release is ready) for the developers site, but that would be fully
complimentary. The Trac wiki would only be used by developers for
design discussions, source compilation instructions, etc.
www.restlet.net -> Trac (http://trac.edgewall.org)
wiki.restlet.org -> Daisy (http://www.daisycms.org)
How does it sounds?
It sounds like I should do an effort to make you stick to Daisy :-)
(as in even for the designer/development discussions )
While I check with Rob and our hosting infrastructure to find a hosting
spot to land this, we can discuss a minimal documentation-structure to
be set up.
Here is what I have in mind:
[1] Main/Entry
* Welcome / What is this, link to [2]
(in fact this should also list the most recent
additions to the documentation section)
* Document-Release overview (lists the various available docs)
(similar to: http://cocoondev.org/daisy/342-cd.html?branch=main)
* How this works
* Self-registration: how to register, and ask for karma
(should be to this list)
* Code of Conduct (what we expect people to do and not do)
* Documentation Principles
(vision on what we want to achieve, anyone to start?)
* Specific Documentation / Tips / StyleGuide to Authors
* writing a section
* using cross-references, footnotes and
* publishing a book
[2] Documentation ! PER RELEASE
* Home (Status of this release, link to other releases)
* Todo's for this documentation release
* The book
> Starting from here is the table-of-contents, again per version
Additionally:
* We need to agree on the level of branching: for which kind of releases
do we build/unify documentation releases? (for every patch-release?
1.0.4, 1.0.5, ... or rather for every minor release: one doc for 1.0.x?
typical advise: to keep up I would guess the number of documented
releases should not exceed 2 per year.)
* Daisy allows for setting up notification emails (similar to commit-mails)
Do we set this up to be sending mails to one of the lists or do we
expect anyone to do that for themselves (actually there are also rss
feeds with changes available)
* Next to that we might agree on marking emails on this list that
discuss the documentation with the label [book]
* I will need some time to work out the docbook thingy (basically it
will boil down to some xslt to convert the daisy-book-xml to docbook.
Any input from someody knowledgeable to docbook to craft out the
template-output is appreciated.
* One of my colleagues built some extension to link up to existing
javadoc. I need to copy that over and install it, but of course only
makes sense
PS: don't worry: there is an automated task in daisy to make a new
branch of your documents based on the old one (I am not suggesting to
rewrite everything from scratch for eveery release :-))
-marc=
Best regards,
Jerome
2007/9/12, Marc Portier <[EMAIL PROTECTED]>:
there is of course a good
(cough) http://www.daisycms.org/ (cough)
way to combine both ideas :-)
you might want to checkout the book-publishing features
http://cocoondev.org/daisydocs-2_1/books/225-cd.html
(based on that a custom publication type to produce docbook should be
quite easy)
(By the way: there are loads of other features that make Daisy a far
better colaborative editorial environment then svn/docbook.)
if nothing else it would surely lower the barrier to entry for people
willing to contribute to docs (which is another profile then people
contributing to code)
lemme know if I can help decide by answering specific questions and/or
lending a hand...
regards,
-marc=
Rob Heittman wrote:
We will try
to launch a Developer Guide effort ASAP. I want to build it with DocBook,
one XML document per chapter, all versionned in SVN and automatically
published on the Restlet.org web site. That will allow contributions via SVN
patches and publication to various output formats.
What do you think of using a wiki (maybe not "The Wiki", wiki.restlet.org)
but, anyway, elect some space for lightweight early collaboration on
documentation in-progress ... with discussion etc, and open to just about
anyone who wants to play. Then, completed work can get put into DocBook
and committed to svn by a committer.
