ignite-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Artem Budnikov <a.budnikov.ign...@gmail.com>
Subject Re: Documenting Ignite
Date Wed, 25 Jul 2018 11:03:07 GMT
Hi Dmitry,

I've added a comment to the issue.

My Confluence ID is a.budnikov. Could you please grant me permissions 
required to edit pages. Thanks!


Artem


On 24.07.2018 16:58, Dmitry Pavlov wrote:
> 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 
> <mailto: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 <mailto: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>
>>>         <mailto: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> <mailto: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> <mailto: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> <mailto: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
>>>>>>>         <mailto: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
>>>>>>>>         <mailto: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