Xavier Hanin wrote:
A wiki is good, but it often lead to inconsistencies when everybody can
contribute. This is good for sharing ideas and community experience, but I
think the core documentation should be under control of the development
team. Moreover, being able to contribute patch to the documentation is a
must IMO (which wasn't the case so far). So using something like xdoc could
be a solution. But what I don't like with xdoc is that it takes time to
generate the documentation to view how it will actually look like.
1. I like docs you can take away with you on your laptop; wikis dont go
offline properly.
2. What is xdoc?
3. Have you had a look at forrest? We use it at work to create HTML+PDF
docs, mostly with .sxw content.
SXW is XML in a Zip file, so could be generated from XHTML source if
need be.
Hence I have worked last month on something which could fit this need, at
least IMO. The idea is to write plain html, with a small header using
javascript to actually format the page. Thus the page is viewable as is
in a
browser with no generation, but handles some basic features such as
- a format a little easier to author than html (the same one as the one we
use in drupal so far, i.e. html + automatic line break + <code> recognition
(including < and > escaping), + automatic recognition of IVY-xxx as jira
links, and some other basic links recognition)
- a navigation tree,
- a template which can easily be changed without modifying all the html
files.
What I've done is not fully working yet, I'll try to find time to make it
better and share with you how ivy doc could look like with this system, to
see if we can consider it as a solution or not.
But maybe others already have ideas on the subject?
Xavier
What do you think?
easyproglife
