[DISCUSS] Version-specific documentation

[Matthias Boehm <mb...@us.ibm.com>]

In the context of SYSTEMML-554, we aim to introduce native frame data type
support. While porting the file-based transform, I intend to drop the
existing transform scaling functionality (mean substraction, z-scoring) as
it is more naturally expressed over matrices. However, this change raises a
general question with regard to our documentation:

How do you feel about maintaining version-specific language references? It
would certainly help to avoid version-specific conflicts (e.g., builtin
functions added in newer versions) but it might add overhead as fixes would
need to go into multiple versions. Personally, I would be in favor of
simply archiving the old documentation (but keeping it available) as part
of our release process.

Regards,
Matthias

Re: [DISCUSS] Version-specific documentation

[Deron Eriksson <de...@gmail.com>]

I would like it if we move towards having a version of the complete
documentation for each release. The documentation for each release can be
published on the main website, similar to what Apache Spark does:
http://spark.apache.org/documentation.html

By the way, this will mean that when we do a release, one task will be to
make sure that the documentation for that release is up-to-date.

Deron


On Wed, Jun 22, 2016 at 10:44 AM, Frederick R Reiss <fr...@us.ibm.com>
wrote:

> Having a separate language reference for each version is a good idea.
> Eventually we will have users running backlevel versions of the system. We
> can cover that need by adding an "archive the current state of the
> documentation" step to our release process.
>
>     Fred
>
>   Sent from my iPhone using IBM Verse
>
>   On Jun 21, 2016, 9:40:31 PM, mboehm@us.ibm.com wrote:
>
>   From: mboehm@us.ibm.com
>   To: dev@systemml.incubator.apache.org
>   Cc:
>   Date: Jun 21, 2016 9:40:31 PM
>   Subject: [DISCUSS] Version-specific documentation
>
>
>      In the context of SYSTEMML-554, we aim to introduce native frame data
> type
>    support. While porting the file-based transform, I intend to drop the
>    existing transform scaling functionality (mean substraction, z-scoring)
> as
>    it is more naturally expressed over matrices. However, this change
> raises a
>    general question with regard to our documentation:
>    How do you feel about maintaining version-specific language references?
> It
>    would certainly help to avoid version-specific conflicts (e.g., builtin
>    functions added in newer versions) but it might add overhead as fixes
> would
>    need to go into multiple versions. Personally, I would be in favor of
>    simply archiving the old documentation (but keeping it available) as
> part
>    of our release process.
>    Regards,
>    Matthias
>

Re: [DISCUSS] Version-specific documentation

[Frederick R Reiss <fr...@us.ibm.com>]

Having a separate language reference for each version is a good idea. Eventually we will have users running backlevel versions of the system. We can cover that need by adding an "archive the current state of the documentation" step to our release process. 
   
    Fred
  
  Sent from my iPhone using IBM Verse
  
  On Jun 21, 2016, 9:40:31 PM, mboehm@us.ibm.com wrote:
  
  From: mboehm@us.ibm.com
  To: dev@systemml.incubator.apache.org
  Cc: 
  Date: Jun 21, 2016 9:40:31 PM
  Subject: [DISCUSS] Version-specific documentation
  
  
     In the context of SYSTEMML-554, we aim to introduce native frame data type
   support. While porting the file-based transform, I intend to drop the
   existing transform scaling functionality (mean substraction, z-scoring) as
   it is more naturally expressed over matrices. However, this change raises a
   general question with regard to our documentation:
   How do you feel about maintaining version-specific language references? It
   would certainly help to avoid version-specific conflicts (e.g., builtin
   functions added in newer versions) but it might add overhead as fixes would
   need to go into multiple versions. Personally, I would be in favor of
   simply archiving the old documentation (but keeping it available) as part
   of our release process.
   Regards,
   Matthias