I am not against having multiple documentation branches -- I am *for* that. I am against emulating our current source code practice of needing to commit twice (two branches) for most things. I think that should be the exception, not the rule. Only during a new dot-zero release would we be compelled to merge forward the changes from the previous branch.
~ David On Fri, Aug 19, 2016 at 11:05 AM Cassandra Targett <[email protected]> wrote: > On Thu, Aug 18, 2016 at 8:48 PM, David Smiley <[email protected]> > wrote: > > > Ugh! I think it's a PITA that we basically always back-port all commits > to > > another branch, and the prospect of having to do this to documentation as > > well will add a large barrier to editing the docs. I propose an > alternative > > way: Like having everything go into a 6x branch and then have the 7x > branch > > be only for things unique to 7x? From time to time and definitely when > 7.0 > > arrives, we then merge 6x into 7x. Some things we will need to remember > to > > remove from 7x, and there will be merge conflicts, but I think the > > down-sides there far outweigh the lower barrier to editing the > > documentation. > > > > I'm not totally following your idea about the branches, but I think > we'd want to use some discretion about what types of changes need to > be backported, and also when an older version is re-published. If you > fix one typo do you need to build the whole Ref Guide again? Seems > overkill. If a page has had a typo for 3 releases, do you need to > backport a small change to all those branches? > > We should agree on some guidelines around this. We can use existing > conventions to start - if you found a typo in the javadocs and chose > to fix it, would you backport it to all the active branches? It seems > to me that people generally don't do that, and I think we could apply > the same principle here. The key point being we could agree to this > and write it down. > > > Make no mistake, for all the numerous benefits of moving to a > source-control > > based editing, it will become harder to make small edits/fixes to the > docs. > > In under 15 seconds I can fix any trivial typo in Confluence. We need to > > recognize this with eyes wide open before choosing the trade-offs. I > still > > think it will be a worthwhile trade-off *if* we strive to make editing > the > > docs in the new system as easy as possible. Needing to usually commit to > > two branches is a *huge* blow to that. As it is, apparently I need to go > > finding some asciidoc IDE that I didn't need yet. Not for typo fixes of > > course, but any way my browser isn't enough any more. > > > > You don't need an IDE. The tools that have been mentioned are only to > preview an Asciidoc page as HTML, as an aid to see your changes as you > make them and not a requirement. Asciidoc is just like Markdown - > mostly the same syntaxes, and the changes are mostly additions to > extend the capabilities of Markdown. But it's a markup language, so > for some edits it's easier to see what it might look like online. > > (By the way, the paragraph I just wrote is 100% valid Asciidoc, no IDE > required.) > > I definitely hear your point about it being really simple to fix small > things today. There is no perfect solution, everything has one > drawback or another. Today you don't have the problem of having to > backport it, because we have no way of having docs for different > versions. If we want maintainable docs for other versions - the idea > came up again a few months ago when the idea of a Solr 5.6 was > initially raised - we'll have to address the issue of how to maintain > those prior versions. > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [email protected] > For additional commands, e-mail: [email protected] > > -- Lucene/Solr Search Committer, Consultant, Developer, Author, Speaker LinkedIn: http://linkedin.com/in/davidwsmiley | Book: http://www.solrenterprisesearchserver.com
