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, 18 Jul 2018 15:39:27 GMT
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
View raw message