Re: New documentation

Thank you, Matthias, for your suggestions!

Matthias Damm schrieb:
> Am 29.04.2006 um 18:37 schrieb Dominik Waßenhoven:
> 
>>We all know that the documentation needs (maybe more than) a
>>face-lifting, because it is an accumulation of worthwile information,
>>but has lost its stringent structure. Thus, I want to give a first
>>outline of a new structure for the documentation, which is derived  
>>from the original one. Any suggestions are appreciated!
> 
> Sounds good after a short view.
> 
> Another thing we should do ASAP is a collection of the things that  
> are missing in the documentation today.

Yes, sure, I didn't mention it, but I also thought of writing the 
documentation as complete as possible.

> To start:
> 
> - All the 0.61 changes are not documented

I disagree here. One of the things that bothered me with the old 
documentation was that the whole ballast of the project development was 
carried along in the documentation. As a user, I don't want to read 
what's new, when I look into the documentation, but I want to know how 
to use the current version of the software. I think the documentation 
should contain everything that is possible with jurabib v0.61, and the 
changes should be documented in the changelog (the more so as this file 
exists already and is well fostered).

> [...]
> 
>>Also, any suggestions for handling the files in the SVN repository are
>>appreciated. [...]
>>
>>a) jbendoc.tex and jbgerdoc.tex stay as they are, and the new
>>documentation files get new names (though I had no good ideas until  
>>now, at least none with only 8 characters...)
>>
>>b) The now existing files will be renamed to jbendoc.old and
>>jbgerdoc.old, and the new ones get the names jbendoc.tex and
>>jbgerdoc.tex (which could lead to confusion).
> 
> c) keep old and new names the same, and create a branch for the doc  
> update in the SVN.
> 
> But probably b) is the best solution.

ACK.

> In the end, the PDFs have to get the same names as today. 
> [...]
> A small problem might occur if jurabib 0.61 is released before the  
> new documentation is finished, but it should be easy to manually add  
> the old version of the doc to the relase package.

Yes, when we follow suggestion b), they are still in the repository 
under the names *.old.

> How do you want to start?
> 
> Would it make sense to implement the new structure in a quick-and- 
> dirty way by just moving around the paragraphs? That might be helpful  
> to see if the new structure works.

That is a possibility, although I would rather start with an empty 
document an put the things from the old doc, that we want to keep, into 
the new doc step by step. IMHO this is easier than to remove paragraphs 
or sentences step by step, because writing a new paragraph/sentence is 
easier than rewording an old one -- at least this is my experience.

Regards,
Dominik.-



 
Yahoo! Groups Links

<*> To visit your group on the web, go to:
    http://groups.yahoo.com/group/jurabib-developer/

<*> To unsubscribe from this group, send an email to:
    [email protected]

<*> Your use of Yahoo! Groups is subject to:
    http://docs.yahoo.com/info/terms/