ignite-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Dmitry Pavlov <dpavlov....@gmail.com>
Subject Re: Documenting Ignite
Date Tue, 24 Jul 2018 13:58:29 GMT
I've noticed now INFRA asks for feedback from us.

Artem, will you provide feedback on done change in
https://issues.apache.org/jira/browse/INFRA-16803

вт, 24 июл. 2018 г. в 11:01, Dmitry Pavlov <dpavlov.spb@gmail.com>:

> Hi Artem,
>
> This is page in Ignite space, so you could do updates. Of course, if you
> have access to Ignite space in wiki. If not, please sign up and share your
> wiki login (id).
>
> Sincerely,
> Dmitriy Pavlov
>
> вт, 24 июл. 2018 г. в 10:25, Artem Budnikov <a.budnikov.ignite@gmail.com>:
>
>> Hi everyone,
>>
>> Despite what I've been told about INFRA, it responded exceptionally
>> quickly and added the field :-)
>>
>> I think the page describing the process of creating IGNITE issues
>> <https://cwiki.apache.org/confluence/display/IGNITE/How+to+Contribute#HowtoContribute-TicketCreation>
>> needs to be updated to reflect the changes related to documentation
>> process. Could someone do this?
>>
>> Cheers,
>>
>> Artem
>> On 23.07.2018 18:00, Artem Budnikov wrote:
>>
>> 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>
>> <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>
>> <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>
>> <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>
>> <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
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message