Hi Joep,
> >> For appendix, it's okay to say it is from a blog, but not withinn a
> >> 'book'. And if we want to prevent duplication of (similar)
> documentation, we
> >> also need to deal with the difference between the main topics (as used
> in
> >> the tutorials and introduction) and all the gory details (for the full
> >> manual).
> >
> > Do we really need to be that formal ??
> I'd rather not, but I hope it is a solution to a problem I suspect.
> But maybe th> ere is no problem or there are better solutions. So please
> > enlighten me!
>
>
No enlightenment, I'm sorry... What we can do is (1) split things as many as
we want, and (2) organize things in subdirectories to "contain" main
subjects: tutorials /{pwm,adc,...}.
I guess there's a treshold between the two: we need to organize things in
dirs, and slit content as needed.
Since we don't precisely know how to do this, I suggest we start to do this
a.s.a.p. We'll re-structure as needed, just like we did with SVN.
As first steps, I'll convert all tutorials on jallib into DITA files. I'll
split content, and we can then discuss what's good, what's wrong, what will
change for the next iteration.
In the meantime, it would be nice to convert jallib intro doc to DITA. I'm
ready to do this, but I guess it could also nice if you could handle this
just to see how it looks like to work with DITA for real.
Finally, I'm about to write some documentation for Jaluino, using DITA.
Maybe few things could be used elsewhere.
And agan finally, we at jal website are also wondering what content could be
put in the website. Some content derived from this documentation could also
be used to "feed" it. Documentation and website projects are dependent from
each other for the content.
>
>
> > I don't see your point about labeling. Would you like ditamap
> automatically
> > built ? Something like "get all document labeled with "tutorial", and put
> > the whole in this section" ? How will you deal with the order ? I think
> just
> > manually assemble ditamap should be enough (pick an intro, pick some
> theory,
> > few tutorials, mix... and voila, a new book).
> It is not about automatic build (although, in time...)
>
> It is about how the introduction document is created: we named the
> topics (say chapters), then for each we wrote an introduction and
> copied the tutorial and deleted large parts of it. But if one day
> there is some change (say, introduction of alias), we need to update
> the tutorials *and* the introduction document derived from it. A
> double (triple, quadruple) maintenance burden...
>
I don't understand. When "alias" is new, you have to update introduction to
talk about this new keyword (just the content about introduction, not the
whole document), and also tutorials, to update jal code I guess. Where is
the maintenance burden ? The fact is if content weren't split, you'd have to
update the document containing intro + tutorials, plus the other document
containing, say, only tutorials.
>
> > With XML, many things can be done, still you have a strict DTD to
> respect.
> > We can derive from a DTD and enrich XML, adapt XSL stylesheets, but then
> > it'll be a real p.i.t.a... IMO.
> This is not what I propose. What I propose is that we create an
> extended dtd for our source and an xsl to convert our source to a
> valid dita document. In other words: a thin pre-processor.
>
>
That's an option. I'm glad we have a XSL guru here for that :)
Cheers,
Seb
--
Sébastien Lelong
http://www.sirloon.net
http://sirbot.org
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"jallib" group.
To post to this group, send email to [email protected]
To unsubscribe from this group, send email to
[email protected]
For more options, visit this group at
http://groups.google.com/group/jallib?hl=en
-~----------~----~----~----~------~----~------~--~---
