Denis, Both yours and Andrey's proposal are important. You should start to vote after the documentation is ready, just like you start to vote after all features are ready, and documentation is just another feature. However, the documentation can't be prepared if there is no information on the features. Implementing the feature and working on the docs should go in tandem. As Andrey pointed out it brings some benefits, and makes you more conscious about the "user" aspect of the feature, which is generally a good thing.
-Artem On Tue, Mar 17, 2020 at 11:59 PM Denis Magda <dma...@apache.org> wrote: > Hi Pavel, > > We're thinking about the same in regards to the future of Ignite > documentation :) Artem and I had some kitchen talks recently and we'll > restart that activity. Ignite definitely deserves and requires next-gen > docs. Artem promised to share his thoughts soon. > > Btw, check out How to write effective documentation for your open-source > projec <https://opensource.com/article/20/3/documentation>t article that I > found in one of my newsletters today. It feels like it can be used as a > reference by Igniters on some best practices. > > Denis Magda > > > On Tue, Mar 17, 2020 at 1:03 PM Pavel Tupitsyn <ptupit...@apache.org> > wrote: > > > I agree with Andrey. > > > > And I'd like to reopen the discussion on "moving docs from readme.io to > > git" [1] [2] > > Looks like we reached some agreement there but never moved on with the > > migration. > > > > > > [1] > > > > > http://apache-ignite-developers.2346864.n4.nabble.com/Move-documentation-from-readme-io-to-GitHub-pages-td16409.html > > [2] https://issues.apache.org/jira/browse/IGNITE-7595 > > > > On Tue, Mar 17, 2020 at 9:48 PM Denis Magda <dma...@apache.org> wrote: > > > > > Andrey, > > > > > > Thanks for sharing your thoughts. Your second point made me recall > > several > > > occasions when only after a release of some public APIs we had a chance > > to > > > complete documentation and discovered the APIs' ineffectiveness and > > oddness > > > from the user usage perspective. But it was already late. > > > > > > Generally, if to move incrementally with documentation process changes, > > > "documentation readiness before the vote" should work as the first step > > for > > > us. There will be delays with the vote for sure because we have to get > > used > > > to this change, but over time we should get to the point when > > documentation > > > will be prepared upon overall task resolution. Andrey, Artem, do you > > agree > > > with that? > > > > > > Other community members, please share your thoughts. If we don't hear > any > > > opposite opinions, then I would update our release procedures with this > > > change. > > > > > > - > > > Denis > > > > > > > > > On Mon, Mar 16, 2020 at 9:44 AM Andrey Gura <ag...@apache.org> wrote: > > > > > > > Denis, > > > > > > > > I agree with you. > > > > > > > > Also I think that we should move to process which will require > > > > documentation updates during work on issue/feature and will part of > > > > code review process. Such approach has some useful benefits: > > > > > > > > - Documentation readiness at the same time when fix/implementation is > > > > ready (remember, documentation is part of a product). > > > > - Work on documentation and review could discover incompleteness of a > > > > fix or a feature on earlier stage (It is usual situation when some > > > > aspects were just forgotten, but documentation writing could > spotlight > > > > such things). > > > > > > > > On Thu, Mar 12, 2020 at 7:49 PM Denis Magda <dma...@apache.org> > wrote: > > > > > > > > > > Igniters, > > > > > > > > > > With the final 2.8 release steps checked out today by announcing > the > > > > > version globally (congrats!), it's a proper time to consider and > > tweak > > > > our > > > > > release process, making completion of some phases more predictable > > and > > > > > aligned. I would like to dedicate this thread solely to changes > > related > > > > to > > > > > the documentation. > > > > > > > > > > If to do a recap, Ignite 2.8 announcement went out of sync with the > > > > > publication of binaries, Maven and other artifacts because our > > > technical > > > > > documentation was completed long after the vote had been closed. > > > > > > > > > > We can easily eliminate such glitches for future releases if agree > to > > > > start > > > > > a vote only if Ignite docs are ready and can be published the same > > day > > > > with > > > > > other release artifacts. If the docs are completed and available > > > > > internally while the vote goes then we can work on a release blog > > post > > > > > (referring to docs details) and announce the release the same day > > when > > > > the > > > > > binaries/docs availability. > > > > > > > > > > Thoughts? Let's change the process ensuring that the vote can be > > > started > > > > > only if technical documentation is ready to be released? > > > > > > > > > > - > > > > > Denis > > > > > > > > > >
