Igniters, I've modified our release process introducing this step that ensures documentation readiness before a vote can be started: https://cwiki.apache.org/confluence/display/IGNITE/Release+Process#ReleaseProcess-4.1EnsureDocumentationReadinessandAccouncementBlogPostActivity
Thanks to everyone who joined this conversation. - Denis On Wed, Mar 18, 2020 at 2:17 AM Artem Budnikov <a.budnikov.ign...@gmail.com> wrote: > 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 > > > > > > > > > > > > > > >
