ignite-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Denis Magda <dma...@apache.org>
Subject Re: Documenting Ignite
Date Thu, 19 Jul 2018 19:01:57 GMT
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
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message