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]
