Maxim, The approach you're suggesting (to keep the docs in a separate repo) was among the two possible options we were reviewing while deciding where to keep the docs. Eventually, we selected the current solution by storing the docs together with the source code in a single repo. As a technical writer, I prefer to have a separate repo but the single-repo approach makes more sense when developers contribute to the docs as well.
Anyway, I wouldn't dump the current approach right away. Let's live with it for some time and see if and how we can optimize and amalgamate docs + dev contribution processes. With ignite-2.9.1, ignite-2.9.2, etc., I would just reuse the same branch - ignite-2.9.0-docs. We can name such branches as ignite-2.9-docs to highlight that that single branch is used for any maintenance version of the ignite-2.9 release. Thoughts? - Denis On Fri, Oct 30, 2020 at 12:16 PM Maxim Muzafarov <mmu...@apache.org> wrote: > Denis, Alex > > It's a bit confusing for me of having the main dedicated branches for > documentation (ignite-2.9-docs, ignite-2.9.1-docs etc.) instead of > keeping docs in the release branch. The drawback of freezing all the > documentation in the release branch is not good for our users also. > > We already have the ignite-extensions will it be better to create a > dedicated repository (like ignite-docs) for the Ignite docs only? I > see the following advantages of this approach: > - release and documentation branches have the same name; > - the ignite-docs master branch always corresponds to the latest Ignite > changes > - scope is not frozen by a happened release > > WDYT? > > On Fri, 30 Oct 2020 at 20:26, Alex Plehanov <plehanov.a...@gmail.com> > wrote: > > > > Igniters, > > > > I've created "ignite-2.9-docs" branch and cherry-picked documentation > > related commits from master. > > If you changing documentation in master branch and this fix should affect > > Ignite 2.9, please cherry-pick this commit to "ignite-2.9-docs" branch > too. > > > > чт, 15 окт. 2020 г. в 01:58, Denis Magda <dma...@apache.org>: > > > > > Igniters, > > > > > > I've put together the first version of the documentation contribution > and > > > publication process that is based on the new documentation engine we're > > > releasing with Ignite 2.9: > > > https://cwiki.apache.org/confluence/display/IGNITE/How+to+Document > > > > > > Please find some time to check it out and suggest any changes. Let's > > > discuss this. At least, I'd like to hear your opinion on the following > > > items: > > > > > > - A relaxed procedure is applied to minor changes (typos, > > > unclarities), with no need to create a JIRA ticket and go through > the > > > pull-request procedure: > > > > https://cwiki.apache.org/confluence/display/IGNITE/How+to+Document#HowtoDocument-ContributingMinorChanges > > > - We're freezing a branch of a release once it's finished. This > makes > > > it impossible to use the release branch for documentation changes > that will > > > follow after. I'm suggesting to create another branch for the docs > needs > > > once the release is finished. @Alex Plehanov < > plehanov.a...@gmail.com> can > > > we try out this approach for Ignite 2.9?: > > > > https://cwiki.apache.org/confluence/display/IGNITE/How+to+Document#HowtoDocument-UpdatingReleasedDocs > > > > > > > > > - > > > Denis > > > > > > > > > On Fri, Mar 20, 2020 at 9:24 AM Denis Magda <dma...@apache.org> wrote: > > > > > >> Hi Maxim, > > >> > > >> Those JIRA labels support the current process that assumes the > creation > > >> of a documentation ticket before a development ticket is closed. If a > > >> contributor believes there is no need to update the docs (like in the > case > > >> of bug fixes) then "Documentation required" will stay disabled. > Otherwise, > > >> we need to work on the docs and "Documentation required" needs to be > on, > > >> and a docs ticket has to be created. That's the current process... > that > > >> should be revisited and changed. I've recorded that item of us in this > > >> discussion: > > >> > http://apache-ignite-developers.2346864.n4.nabble.com/DISCUSSION-Major-changes-in-Ignite-in-2020-td46579.html > > >> > > >> Generally, I like the idea shared by Andrey Gura that documentation > and > > >> APIs need to be updated and prepared before a primary development > ticket is > > >> closed. As a side effect, we'll get rid off "Documentation required" > label. > > >> > > >> - > > >> Denis > > >> > > >> > > >> On Fri, Mar 20, 2020 at 7:03 AM Maxim Muzafarov <mmu...@apache.org> > > >> wrote: > > >> > > >>> Denis, > > >>> > > >>> From my recent practice with the release check-boxes "Release notes > > >>> required" and "Documentation required" also was not so helpful as > > >>> expected. Can we remove them from JIRA issues? > > >>> > > >>> There is no magic pill to not forget to document improvements, but I > > >>> think a wide discussion of each major improvement on the dev-list can > > >>> help much to keep documentation up to date. > > >>> > > >>> On Thu, 19 Mar 2020 at 23:18, Alexey Zinoviev < > zaleslaw....@gmail.com> > > >>> wrote: > > >>> > > > >>> > The Best way to require draft documentation with the proposed PR:) > as a > > >>> > part of TC check > > >>> > > > >>> > чт, 19 мар. 2020 г., 21:06 Denis Magda <dma...@apache.org>: > > >>> > > > >>> > > 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 > > >>> > > > > > > > > > >>> > > > > > > > > >>> > > > > > > > >>> > > > > > > >>> > > > > > >>> > > > > >>> > > >> >
