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 Wed, 18 Jul 2018 20:21:15 GMT
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