Re: Maintaining documentation consistency on readme.io

[Denis Magda <dm...@apache.org>]

Igniters,

We’re approaching 1.9 release and some of you will be updating the documentation on readme.io. Let me remind you how the documentation has to be updated if you’re adding a feature that is missing in 1.8.

1) DO NOT create any new version of the document until the release. If you want to add any new document pertaining to the next release, create it within the document for the current version and keep the page hidden. 

If you need to update an existing page then clone it, name as {page-name-new-version}, refine and left hidden.

2) Send all the documentation updates for review to Denis Magda and Prachi Garg.

Documented on the wiki:
https://cwiki.apache.org/confluence/display/IGNITE/Documentation <https://cwiki.apache.org/confluence/display/IGNITE/Documentation>

—
Denis

> On Oct 12, 2016, at 9:57 AM, Prachi Garg <pg...@gridgain.com> wrote:
> 
> To make changes for the existing pages, creating a clone of the page would be my suggestion too, and readme.io <http://readme.io/> provides this feature.
> 
> -P
> 
> On Wed, Oct 12, 2016 at 9:15 AM, Denis Magda <dmagda@gridgain.com <ma...@gridgain.com>> wrote:
> We can create a copy of an existing page then and make it hidden. At the time 1.8 gets released the page will become a primary one and the old one will be removed.
> 
> Prachi, do you have other approaches in mind?
> 
> —
> Denis
> 
>> On Oct 12, 2016, at 1:39 AM, Alexey Kuznetsov <akuznetsov@gridgain.com <ma...@gridgain.com>> wrote:
>> 
>> Hi,
>> 
>> +1 to Vova question.
>> How should I modify existing page if my modification intended for 1.8 release?
>> 
>> 
>> On Wed, Oct 12, 2016 at 3:23 PM, Vladimir Ozerov <vozerov@gridgain.com <ma...@gridgain.com>> wrote:
>> Hi,
>> 
>> As far as I remember, I created v1.8 for https://apacheignite-fs.readme.io/ <https://apacheignite-fs.readme.io/> and made some changes there. These changes are not relevant anymore, so please go ahead and remove it.
>> However, I am concerned with proposed process. What is the process if I need to modify existing page? 
>> 
>> Vladimir.
>> 
>> 
>> On Wed, Oct 12, 2016 at 2:57 AM, Denis Magda <dmagda@gridgain.com <ma...@gridgain.com>> wrote:
>> Guys,
>> 
>> Who exactly created version 1.8 in our documentation? Please remove it and follow Prachi’s suggestions below.
>> 
>> —
>> Denis
>>  
>>> On Oct 11, 2016, at 4:21 PM, Prachi Garg <pgarg@gridgain.com <ma...@gridgain.com>> wrote:
>>> 
>>> Engineers,
>>> 
>>> I see that version 1.8 is created on readme.io <http://readme.io/>. As discussed in this email thread below, please DO NOT create any new version of the document until the release. If you want to add any new document pertaining to the next release, create it within the document for the current version and keep the page hidden. 
>>> 
>>> I request you to please move your changes from 1.8 to 1.7, so that I can delete 1.8 from readme.io <http://readme.io/>.
>>> 
>>> 
>>> Thanks,
>>> -Prachi
>>> 
>>> 
>>> 
>>> ---------- Forwarded message ----------
>>> From: Prachi Garg <pgarg@gridgain.com <ma...@gridgain.com>>
>>> Date: Tue, Sep 6, 2016 at 3:43 PM
>>> Subject: Re: Maintaining documentation consistency on readme.io <http://readme.io/>
>>> To: dev@ignite.apache.org <ma...@ignite.apache.org>
>>> 
>>> 
>>> Fixed. 
>>> 
>>> That's why I recommend that from now on we maintain only version at a time :)
>>> 
>>> -P
>>> 
>>> On Tue, Sep 6, 2016 at 12:35 PM, Igor Rudyak <irudyak@gmail.com <ma...@gmail.com>> wrote:
>>> It looks like after copying Ignite-Cassandra module documentation from
>>> version 1.6 to 1.7 it became slightly inconsistent.
>>> 
>>> For example Ganglia dashboard screenshot appeared in "Deployment" (
>>> https://apacheignite.readme.io/docs/aws-infrastructure-deployment#deployment <https://apacheignite.readme.io/docs/aws-infrastructure-deployment#deployment>)
>>> while it should be at the end of "Monitoring" section (
>>> https://apacheignite.readme.io/docs/aws-infrastructure-deployment#monitoring <https://apacheignite.readme.io/docs/aws-infrastructure-deployment#monitoring>
>>> )
>>> 
>>> Igor
>>> 
>>> 
>>> On Tue, Sep 6, 2016 at 11:50 AM, Prachi Garg <pgarg@gridgain.com <ma...@gridgain.com>> wrote:
>>> 
>>> > Fixed. Thanks for pointing it out!
>>> >
>>> > -P
>>> >
>>> > On Sat, Sep 3, 2016 at 9:07 PM, 李玉珏@163 <18624049226@163.com <ma...@163.com>> wrote:
>>> >
>>> > > Prachi:
>>> > >
>>> > > https://apacheignite.readme.io/v1.6/docs/aop-based-grid-enabling <https://apacheignite.readme.io/v1.6/docs/aop-based-grid-enabling>
>>> > >
>>> > > this doc is missing in the 1.7 version.
>>> > >
>>> > >
>>> > > 在 16/8/26 02:50, Prachi Garg 写道:
>>> > >
>>> > > Right!
>>> > >>
>>> > >>
>>> > >> On Thu, Aug 25, 2016 at 10:28 AM, Dmitriy Setrakyan <
>>> > >> dsetrakyan@apache.org <ma...@apache.org>>
>>> > >> wrote:
>>> > >>
>>> > >> Got it. So essentially you are proposing to make the changes for the
>>> > >>> existing version, but hide the new pages, until the next version is
>>> > >>> released, right?
>>> > >>>
>>> > >>> On Thu, Aug 25, 2016 at 10:24 AM, Prachi Garg <pgarg@gridgain.com <ma...@gridgain.com>>
>>> > >>> wrote:
>>> > >>>
>>> > >>> Changes to the existing pages will still have to be copied manually;
>>> > but
>>> > >>>> since we are not maintaining two versions (current and future) at the
>>> > >>>>
>>> > >>> same
>>> > >>>
>>> > >>>> time, it may be a lesser overhead. Once a new version is released, we
>>> > >>>> hardly go back to the previous versions to fix anything.
>>> > >>>>
>>> > >>>> -P
>>> > >>>>
>>> > >>>> On Wed, Aug 24, 2016 at 9:42 PM, Dmitriy Setrakyan <
>>> > >>>>
>>> > >>> dsetrakyan@apache.org <ma...@apache.org>>
>>> > >>>
>>> > >>>> wrote:
>>> > >>>>
>>> > >>>> Prarchi, great idea. We should follow it.
>>> > >>>>>
>>> > >>>>> However, this addresses only new content. What about changes to the
>>> > >>>>> existing pages?
>>> > >>>>>
>>> > >>>>> D.
>>> > >>>>>
>>> > >>>>> On Wed, Aug 24, 2016 at 5:15 PM, Denis Magda <dmagda@gridgain.com <ma...@gridgain.com>>
>>> > >>>>>
>>> > >>>> wrote:
>>> > >>>>
>>> > >>>>> Prachi,
>>> > >>>>>>
>>> > >>>>>> This is an excellent idea!
>>> > >>>>>>
>>> > >>>>>> Would you mind adding a new page to this [1] section?
>>> > >>>>>>
>>> > >>>>>> After the page is ready we also need to leave a reference to it
>>> > under
>>> > >>>>>>
>>> > >>>>> this
>>> > >>>>>
>>> > >>>>>> [2] section.
>>> > >>>>>>
>>> > >>>>>> [1] https://cwiki.apache.org/confluence/display/IGNITE/ <https://cwiki.apache.org/confluence/display/IGNITE/>
>>> > >>>>>>
>>> > >>>>> Development+Process
>>> > >>>>>
>>> > >>>>>> <https://cwiki.apache.org/confluence/display/IGNITE/ <https://cwiki.apache.org/confluence/display/IGNITE/>
>>> > >>>>>>
>>> > >>>>> Development+Process>
>>> > >>>>
>>> > >>>>> [2] https://cwiki.apache.org/confluence/display/IGNITE/How+ <https://cwiki.apache.org/confluence/display/IGNITE/How+>
>>> > >>>>>> to+Contribute#HowtoContribute-Documentation&examples <
>>> > >>>>>> https://cwiki.apache.org/confluence/display/IGNITE/How+ <https://cwiki.apache.org/confluence/display/IGNITE/How+>
>>> > >>>>>> to+Contribute#HowtoContribute-Documentation&examples>
>>> > >>>>>>
>>> > >>>>>> —
>>> > >>>>>> Denis
>>> > >>>>>>
>>> > >>>>>> On Aug 24, 2016, at 10:58 AM, Prachi Garg <pgarg@gridgain.com <ma...@gridgain.com>>
>>> > >>>>>>>
>>> > >>>>>> wrote:
>>> > >>>>
>>> > >>>>> Igniters,
>>> > >>>>>>>
>>> > >>>>>>> Since readme.io <http://readme.io/> does not automatically copy the changes from the
>>> > >>>>>>>
>>> > >>>>>> current
>>> > >>>>>
>>> > >>>>>> version to the subsequent version, I have the following suggestion:
>>> > >>>>>>>
>>> > >>>>>>> Create the document for future releases within the document for the
>>> > >>>>>>>
>>> > >>>>>> current
>>> > >>>>>>
>>> > >>>>>>> version, and keep the pages hidden. After the new release, create
>>> > >>>>>>>
>>> > >>>>>> the
>>> > >>>
>>> > >>>> new
>>> > >>>>>
>>> > >>>>>> version for the document and unhide the pages.
>>> > >>>>>>>
>>> > >>>>>>> This way we don't have to manually copy the document between the
>>> > >>>>>>>
>>> > >>>>>> two
>>> > >>>
>>> > >>>> versions.
>>> > >>>>>>>
>>> > >>>>>>> Thoughts?
>>> > >>>>>>>
>>> > >>>>>>> -Prachi
>>> > >>>>>>>
>>> > >>>>>>
>>> > >>>>>>
>>> > >
>>> > >
>>> >
>>> 
>>> 
>> 
>> 
>> 
>> 
>> 
>> -- 
>> Alexey Kuznetsov
>> GridGain Systems
>> www.gridgain.com <http://www.gridgain.com/>
> 
>