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 Wed, 18 Jul 2018 21:49:35 GMT
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
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message