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 08:01:58 GMT
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