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 > > > > > >
