lucene-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Cassandra Targett <casstarg...@gmail.com>
Subject Re: Proposal to Move Solr Ref Guide off Confluence
Date Fri, 19 Aug 2016 15:04:56 GMT
On Thu, Aug 18, 2016 at 8:48 PM, David Smiley <david.w.smiley@gmail.com> 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: dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: dev-help@lucene.apache.org


Mime
View raw message