Re: [docbook] Newbie question - what schema should I use?

["mark boylan" <markboylan@hotmail.com>]

Jose,

I sent the document seperately.

Yes I do use cvs. I keep my project documentation right with my project 
source code in an xdocs directory.  My build scripts keep the html & pdf 
documents up to date along with the source code.  I use ant to build, test 
and deploy everything.  It copies the docbook output, along with the 
javadocs, to-do lists, test results, and other stuff right to my project 
website.

I usually work alone or on small teams, so having the documentation in one 
file is generally not a problem.  But if I were working with a large group, 
I would definately consider breaking the documentation into many smaller 
files, and I'd still use cvs.

In that case, I would probably create a document home page by hand that 
would contain links to the generated html for each of the smaller documents. 
  Maybe like a frameset, with a narrow index on the left, and the 
documentation html on the right.  Of course, the html output of each 
document would have its own subdirectory to prevent overwriting the previous 
document's files.  I think this would still be fairly easy to manage and 
automate.

hope this helps

- mark


>
>    Mark, Bob,
>
>    Could I have that document to take a look at it?
>
>    Juat another question, do you use CVS? This is another thing I'm taking 
>into account, because a lonely big xml docbook could be more difficult to 
>control than several small ones because of continuated conflicts, merges, 
>etc.
>
>    Thank you very much, regards
>    Jose
>
>mark boylan wrote:
>
>>Hi Jose,
>>
>>I use docbook for my project documentation.
>>
>>I keep all of my documents in a set. Each book in the set represents a 
>>major division in the documentation. One book for the project plan, one 
>>book for the business analysis, another for the system documentation.  I 
>>have chapters for actors, use cases, iteration plans etc...
>>
>>I'm not sure if it's the best way, but that's how I do it. And yes, I try 
>>to use xrefs as much as possible. You can also use ulinks to external 
>>artifacts like models, javadocs and test results.
>>
>>I just started creating a document for a new project and I have a rough 
>>template. If you'd like me to send it to you, email me off list.
>>
>>- mark
>>
>>
>>>    Hi there,
>>>
>>>    I would like to use docbook as the format for the documentation in 
>>>several projects I'm working on now. The idea is having a set of related 
>>>documents, in a tree hierarchy, containing, among other things, the 
>>>requirements of the application specified as use cases. One of the things 
>>>I need in this documentation is to be able to link to other documents, so 
>>>I don't have duplicated and/or bloated specifications, making the 
>>>documentation more readable. So now the questions:
>>>
>>>    I thought about using the simple docbook schema, as I don't need a 
>>>lot of the things that appear in the whole schema, but this schema 
>>>doesn't seem to support linking between documents. So what's the best 
>>>solution? Should I go for the whole schema? Or is there any way to link 
>>>between documents using the simple schema? (I forgot to mention... the 
>>>main output format will be html). Maybe instead of having a lot of small 
>>>documents I should have just a dockbook document for the whole 
>>>documentation set and generate from this several html documents with 
>>>links to each other? How can I achieve any of the above (I mean, what 
>>>tools should I use)?
>>>
>>>    Any advice would be greatly appreciated.
>>>
>>>    Thanks in advance, regards
>>>    Jose
>>>
>>>
>>>---------------------------------------------------------------------
>>>To unsubscribe, e-mail: docbook-unsubscribe@lists.oasis-open.org
>>>For additional commands, e-mail: docbook-help@lists.oasis-open.org
>>>
>>
>>_________________________________________________________________
>>Protect your PC - get McAfee.com VirusScan Online  
>>http://clinic.mcafee.com/clinic/ibuy/campaign.asp?cid=3963
>>
>

_________________________________________________________________
Add photos to your e-mail with MSN 8. Get 2 months FREE*.  
http://join.msn.com/?page=features/featuredemail