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 Thu, 19 Jul 2018 19:58:17 GMT
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
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message