This is the mail archive of the docbook@lists.oasis-open.org mailing list for the DocBook project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

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


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



--------------------------------------------------------------------- To unsubscribe, e-mail: docbook-unsubscribe@lists.oasis-open.org For additional commands, e-mail: docbook-help@lists.oasis-open.org


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]