Re: [open-cobol-list] next release

[Thomas Biehler]

On Saturday 21 February 2004 03:05, Keisuke Nishida wrote:
> Documentation :(  The manual does not cover the new features yet.
> I'd like to update it before making a new release.  Can anybody help?

Well, documentation is always a topic!   (and so unpopular)  :-)

I don't know if i can help!
I think, i can better help with (growing of) the TODO-list !  :-))

I have too many questions and only less answers:
====================================
- which features are (new) implemented ?
  run the test-scripts with "-l" should give some hints,
  but are there always testscripts for new features ?
  I don't think so. --> a good goal for the future!

- if a script run's about cvs to evaluate the log messages,
  this can gives hints, but are the log messages good (verbose) enough?
  --> short, but not to short here is a good way!

So, i think this is part, who only you are able to do.  :-(
(With the help of your memory)
But perhaps i am wrong here.
(I hope, there will be more people able to do this in future)

For the future i can imagine:
================================================
- Make a "unimplemented_feature.at" and "in_work_feature.at"
  for new (= requested) or in_working features in the tests-directory.
  (which then are always failing!)
  Then the step, descriped above, would much more help.
  (IMO: the both scripts would not run with "make check"!
  a new make target or explicit, manuelly start would be ok!),
  If the feature is (good enough) implemented,
  the used autotests could be moved into other test-scripts!

-> ALWAYS explicit log new features in cvs ( commit)
    so a cvslog-script (Do you have a favorit ?)  could be helpfull !

-> update of documentation to cvs must then follow (nearly) immediatly,
    if not the situation will be as it is now. :-(


But there are many other topics:
======================================================
Documentation should be availabe online and in form to be (pretty) printed.
One source (metaformat) who many users can write parallel should be in CVS.

Well!  You use texinfo for this. Not a bad choice!

With a good toolchain you can generate .info, .man, .html,  .ps, .pdf. ...
(This should be documented well in the "manual", which tools,
 which versions of the tools ==> toolchain)
I had some trouble in past with the "toolchain" on
different system's / distributions.

Do you stick with this format?
I am not familar with writing texinfo.  :-(
Which editor/ide  or other tool do you use?
EMACS ?  (Escape, Meta, Alt, Control, Shift)  :-)
(  I don't use EMACS. IMHO not a editor, it is a big ide !  )
I use vi (vim). I can not change to EMACS for writing documentation.
I hope you can understand me.  ;-)
Perhaps i should learn to write texinfo with some (other) tool!?
Could you give me some recommendations?

I would prefer writing documentation with other tools / format.
Docbook (XML) with modern tools (open-office?).
That could i integrate better with my other work.
But a good toolchain is here also a topic!  :-(
But i also have to learn something here.
This needs some time!

---> Sorry,  i can not really support you with writing documenation now.
( Perhaps, someone else can be found. )

Do you know any good converters between texinfo <--> docbook/xml?
(Both directions !?)

What is the audience of the (manual) book ?
(developers, programers, porters, beginners, adminstrators .... ?)

Split it into different books  (now, later, when, who  ...) ?
FAQ ?
Which info to the website  (status-page?)  ?
  -> how , developer corner ...?
The website into cvs ?

Which content into the documenation?

- Documentation of the configuration files. (syntax/meaning) ?
  I think config-options will be changed, renamed , added
  often for a quite long time! --> short documenation now

- Documentation of the status (release-version , and cvs-snapshots!)
  --> should be always update!
- Documentation of the os(es) which are supported. (configure / parameter)
  (success storys, problems)

- Which "cobol"-dialect style / extensions form (other compilers)
  are supported. (which parameter activates a feature ?)

- a Language Reference Manual  --> IMO: is much more later needed!

- Which package formats are available?

- Hints, how to easy debug ...

- Hints, how to port from a commercial compiler
...

=======================================================

But STOP!!!!

The next release number is 0.30,  yes ?

There are many numbers until  1.00 !   ;-)

IMHO, only a couple of the tasks above, have to be done until
the 0.30  release.  (I agree with you, the new features should be listed!)
The next release  (0.3x  / 0.4x?) could take some more.
(But i don't think all at once!).

I was saying, a release strategy is TODO.
Do you agree with me, now ?   :-)

But, i do not want a (fix) schedule!  Releases should be made (only)
if enough things have changed for the convenince of the users!
   (==> developer-releases are something others)
My recommendation: Release not to often, but also not to seldom!
One (stable) release in  ~  a year or half a year is ok.
But this has to be decided from case to case.
(Note: packagers and adminstrators, (distributors) are also users)


Thomas

P.S. good documentation is always difficult to reach/manage!
       a good infrastructure is a very important prerequisite!

P.P.S   I will send some other requests first.   ("small" requests)
           (my TODO list is not empty, it grows again ...  ;-) )