Menu
▾
▴
[generguide-devel] More notes about Users Guide
|
From: Cameron S. <ca...@sh...> - 2003-10-26 20:58:10
|
There is a lot of content in the Users Guide which duplicates content I've already put together. I think we need to determine what content goes into which document. Apart from a couple of common sections, I assume we don't want to have the same content in multiple web pages, and we certainly don't want the same content in different source docs as it creates a maintainence problem. -- Abstract: I think you can probably draw some text from my "Abstract". -- System Overview: I'd imagine that this section could almost include a lot of text from my "About" section. I'd add to my "About" -- Figure 2: High-Level Architecture: This diagram doesn't describe the architecture. I suggest that you don't need a diagram to explain the architecture, your text is enough. I'd keep your Introduction/System Overview/Generguide. (nice break down of concepts). However I think it doesn't describe "what is unique" about generguide. This is what I tried to address in my "About" section and "Abstract". -- I think you need to explain what the following list terms mean: Distributed Authoring Structured Authoring Context Reuse Single-Sourcing -- Command Line Processing Model/process steps: You have correctly documented the current code, however now we have a generconfig.xml we are going to remove the logic where local sections overwrite generguide sections. Ie, steps 1 and 2 have been removed. Step 3 processes the generconfig.xml to selectively include external sections. -- CGI processing model: I think this logic is too much detail for a users guide. It belows in a design guide. I assume a users guide should focus on how you drive the Web pages. -- Docbook I think you should mention that original docbook was not XML and that we only support XML versions of docbook. Ie, users will need to convert their docbook to docbook XML before we can process it. -- Micrsoft Word and others: I think that somewhere we need to acknowledge that the majority of business docs are currently written in Word format. We should have a policy on word docs. Should we support it? If not, why not. Is it possible to create a word template which maps to docbook tags? If so, can we then transform word docs to docbook? -- Got to go to work now. I will be online again morning and night (Sydney time). I often have my computer connected, but am running round the house making breakfast and the like. If you try and contact me via ICQ, my computer beeps and I should be able to hear it. So You might consider installing ICQ. Still reviewing ... -- Cameron Shorter http://cameron.shorter.net Open Source Developer http://generguide.sourceforge.net http://mapbuilder.sourceforge.net http://geotools.org Senior Software Engineer http://www.adi-limited.com |
