ignite-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Artem Budnikov <a.budnikov.ign...@gmail.com>
Subject Re: Documenting Ignite
Date Mon, 23 Jul 2018 15:00:29 GMT
Hi everyone,

I created an issue in the Apache INFRA project: 
https://issues.apache.org/jira/browse/INFRA-16803

Cheers,

Artem


On 19.07.2018 22:58, Dmitry Pavlov wrote:
> I appologize, initially I misundersood proposal. I've concluded that new
> doc issue will be created automatically by closing original ticket, - this
> can be done by plugin only.
>
> If we just introduce flag or combobox for indicate doc is required, there
> is no technical issues, it is defenetely possible. So +1 from my side
> without concerns.
>
> чт, 19 июл. 2018 г. в 22:02, Denis Magda <dmagda@apache.org>:
>
>> Ok, if all our doc writers are in the agreement then let's give a couple of
>> days to our fellow Igniters to share alternate opinions.
>>
>> Artem, if you don't hear back by Monday then feel free to create an INFRA
>> ticket.
>>
>> --
>> Denis
>>
>> On Thu, Jul 19, 2018 at 10:43 AM Prachi Garg <pgarg@gridgain.com> wrote:
>>
>>> I totally agree with Denis's point -
>>>
>>> "Another benefit of having "Docs Required" flag enabled by default, is
>> that
>>> Artem and Prachi can see all such tickets months and weeks before a
>>> release, figure out details from source code contributors and complete
>> the
>>> docs in advance."
>>>
>>> On Wed, Jul 18, 2018 at 2:49 PM, Dmitry Pavlov <dpavlov.spb@gmail.com>
>>> wrote:
>>>
>>>> Yes, I agree. My concern is related only to process implementation
>> aspect,
>>>> I wonder if it is technically possible.
>>>>
>>>> Generally I like idea of automatic control.
>>>>
>>>> ср, 18 июл. 2018 г. в 23:21, Denis Magda <dmagda@apache.org>:
>>>>
>>>>> Hi folks,
>>>>>
>>>>> Artem's proposal might simplify and make our doc tickets tracking less
>>>>> error-prone. The current approach implies that a contributor keeps in
>>>> mind
>>>>> what needs to go to the docs. If he/she has a good memory, a doc JIRA
>>>>> counterpart will be created once the contribution is accepted. But the
>>>>> practice shows that the memory lets us down :)
>>>>>
>>>>> Another benefit of having "Docs Required" flag enabled by default, is
>>>> that
>>>>> Artem and Prachi can see all such tickets months and weeks before a
>>>>> release, figure out details from source code contributors and complete
>>>> the
>>>>> docs in advance.
>>>>>
>>>>> --
>>>>> Denis
>>>>>
>>>>> On Wed, Jul 18, 2018 at 8:39 AM Artem Budnikov <
>>>>> a.budnikov.ignite@gmail.com> wrote:
>>>>>
>>>>>> Dmitry,
>>>>>>
>>>>>> The goal I had in mind by proposing that suggestion was to rectify
>> the
>>>>>> fact that JIRA issues for documentation are created on an ad-hoc
>> basis,
>>>>>> and often issues are created when the lack of documentation becomes
>> an
>>>>>> issue for somebody. So we need to be more proactive.
>>>>>>
>>>>>> I think manual tracking of issues is possible but as efficient as
the
>>>>>> current situation with the docs. Manual tracking will have to be
>> shared
>>>>>> between multiple contributors and performed outside of JIRA, which
>> has
>>>>>> its own limitation. If you have any suggestions for improvement
>> without
>>>>>> creating fields in JIRA, please share your thoughts.
>>>>>>
>>>>>> If you are concerned that it's not possible to add a field, then
we
>>>>>> should contact Apache Infra and find out.
>>>>>>
>>>>>>
>>>>>> Best regards,
>>>>>>
>>>>>> Artem Budnikov
>>>>>>
>>>>>>
>>>>>> On 18.07.2018 16:14, Dmitry Pavlov wrote:
>>>>>>> Hi Artem,
>>>>>>>
>>>>>>> I sometimes receive feedback that Ignite docs has potential for
>>>>>>> improvement, while I found our docs quite intuitive and simple
to
>>>>>>> understand. So if experienced tech writer will join community
it
>>>> could
>>>>>>> benefit all of us, and users, of course. So you're very welcome
to
>>>> the
>>>>>>> community!
>>>>>>>
>>>>>>> About idea of fields introduction I guess we will need assistance
>> of
>>>>>> Apache
>>>>>>> Infra team, because Ignite shares JIRA with all other Apache
>> project.
>>>>>> And
>>>>>>> I'm not sure that technical implementation of proposed process
is
>>>> even
>>>>>>> possible without plugins. Could we consider some manual processing
>> of
>>>>>>> completed issues in relation to doc requrement?
>>>>>>>
>>>>>>> Sincerely,
>>>>>>> Dmitriy Pavlov
>>>>>>>
>>>>>>> ср, 18 июл. 2018 г. в 15:06, Artem Budnikov <
>>>>>> a.budnikov.ignite@gmail.com>:
>>>>>>>> Hi Igniters,
>>>>>>>>
>>>>>>>> Being a technical writer, I'm going to contribute to Ignite's
>>>>>>>> documentation, and I believe documentation is an important
part of
>>>>>> every
>>>>>>>> product, especially such a complex product as Apache Ignite.
>>>>>>>>
>>>>>>>> I'd like to put forward a suggestion on how to increase our
>> chances
>>>> of
>>>>>>>> making Ignite documentation more comprehensive. The basic
idea is
>> to
>>>>>>>> have a Jira issue with the Component field set to "Documentation"
>>>> for
>>>>>>>> every feature that needs to be documented. This will ensure
that
>>>> there
>>>>>>>> are documentation issues that cover the entire product
>>>> functionality.
>>>>>>>> Then someone can take on an issue and contribute an article
on the
>>>>>> subject.
>>>>>>>> This is how I envision it to work technically. A new field
>>>> (checkbox)
>>>>>> is
>>>>>>>> added to the Apache Ignite Jira project. The checkbox indicates
>> that
>>>>>> the
>>>>>>>> feature requested in this issue needs to be documented. The
>>>> checkbox is
>>>>>>>> selected by default. If the feature does not require
>> documentation,
>>>>>> then
>>>>>>>> the author unchecks the checkbox. If it does require
>> documentation,
>>>> the
>>>>>>>> author creates a related Jira issue selecting "Documentation"
in
>> the
>>>>>>>> Component field, providing details on what exactly should
be
>>>>>> documented.
>>>>>>>> The field is called "Requires documentation" or similarly.
It
>> could
>>>> be
>>>>>>>> also useful to create a new issue type for documentation
issues
>>>>>>>> exclusively.
>>>>>>>>
>>>>>>>> Once this is done, we'll be able to filter out
>>>>>>>>
>>>>>>>>    1. issues that do not require documentation,
>>>>>>>>    2. issues that have related documentation tickets, and
>>>>>>>>    3. issues that require documentation but have no related
issues
>>>>>> (which
>>>>>>>>       means that the author forgot to create a documentation
issue
>>>> for
>>>>>> it).
>>>>>>>>
>>>>>>>> Please share your thoughts about this.
>>>>>>>>
>>>>>>>>
>>>>>>>> Best regards,
>>>>>>>>
>>>>>>>> Artem Budnikov
>>>>>>>>
>>>>>>>>
>>>>>>
>>>


Mime
View raw message