Re: [Netatalk-devel] State of the Docs

[Thomas K. <Tho...@ph...>]

Bolke de Bruin wrote:

> Is there somekind of checklist available for what needs to be done?

* get in contact with one of the project maintainers and let them add you to
  the netatalk project (you won't be able to do any of the tasks outlined
  above without that)

* get the CVS changelog and check every single entry meticulously

* correct the manual pages as well as the documentation for every single
  patch that has been applied so the documentation is always in sync with
  the software (please keep in mind that spending an enormous amount of time
  on the docs for version 2.0 is the main reason why whe have that low
  traffic on netatalk-admins. And please compare with the situation prior to
  2.0 where we had different sorts of documents covering different aspects
  of Netatalk being more or less out of date/sync with Netatalk's
  development status that caused frustration)

  - major reworks or new features might require a separate chapter in the
    docs
  - features that only work on specific platforms need to be mentioned
    specially 
  - new OS versions might require adjustments of the docs (hints how
    specific problems on specific platforms might be solved and the like)
  - hints in the docs how to build netatalk on specific platforms might be
    outdated and should be removed

* weigh every patch applied since the lasta release and generate the
  relevant lines for the NEWS file, add the stuff and generate an HTML
  version of this file

* check out the manual pages from the netatalk-docs CVS tree

* convert the XML based manual pages into manual pages

* check them in into the normal CVS tree

* adjust the VERSION

* check the whole stuff out

* create a tarball from it

* unpack the tarball and (let others) test on every platform Netatalk
  currently supports and fix the bugs introduced by patches not widely
  tested so far (and believe me... there are many)

* test and fix!

* test and fix!

* relax a bit

* test and fix!

* write/correct the release notes, create an HTML version of this file
  (some tools available: http://netatalk.sourceforge.net/2.0/utils/)

* create both HTML documentation as well as PDF documentation from the
  docbook stuff

* get in contact with one of the project maintainers to give him both
  tarball as well as release notes

* make an appointment regarding release date

* at the same time one of the project maintainers officially releases the
  new version put everything at the correct location at netatalk.sf.net:

  - HTML docs at http://netatalk.sourceforge.net/2.0/htmldocs
  - PDF docs at http://netatalk.sourceforge.net/2.0/Netatalk-Manual.pdf
  - changelog: http://netatalk.sourceforge.net/2.0/ChangeLog
  - NEWS: http://netatalk.sourceforge.net/2.0/NEWS.html
  - Release notes: http://netatalk.sourceforge.net/2.0/ReleaseNotes.html

* finally adjust http://netatalk.sourceforge.net to reflect the changes.

* In case a major update is on the run release a press statement

Hey... and now you're done -- it's really that simple. Good luck :-)

Due to lack of spare time I'm not able to participate in this process any
longer. But I strongly recommend to not change or remove any step of the
above because the quality level we've reached with 2.0 should be kept IMO.

Regards,

Thomas