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.ign...@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.ign...@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 > >> > >> > >
