Open Stack

----- Original Message -----
> From: "Nicholas Chase" <nchase at mirantis.com>
> To: openstack-docs at lists.openstack.org
> Sent: Thursday, October 31, 2013 8:58:03 AM
> Subject: Re: [Openstack-docs] Integrating Ask OpenStack in docs
> 
> >> Another use case could be - via inserting markers into the text of
> >> the doc page where the questions are or around the paragraphs. When
> >> you click on the marker - a corresponding question opens in the
> >> sidebar. I.e. - questions can be tied to specific paragraphs, where
> >> possible.
> >>
> >> If a paragraph does not have questions - hovering over the text of
> >> the doc page will display a prompt to "ask a question" about the
> >> paragraph over which the pointer is hovering.
> 
> I'm having flashbacks here; I just came off a (very long) project that
> aimed to do EXACTLY this.  The problem that we ran into was that, just
> as in this case, we are talking about living documents; are you
> proposing inserting the markers directly into the XML?

I think we would have to handle this in the transformation and ultimately the output (via JavaScript and an external data source/provider) rather than the source XML - after all we're hopefully not going to rebuild the guide every time somebody posts a relevant question.

> If not, how will you track the specific paragraph between versions?

I don't think we can (realistically) go down to the paragraph level but we (almost?) always have an ID at the section level to key off. I think this might have been a requirement, in addition to the book level identifiers, for the existing disqus stuff to work?

> If so, how will you insert those markers?  Check them out, edit them,
> and check them back in?  Will they have to go through the typical review
> process?

The main difficulty here will be tracking which question someone ended up posting when we redirect them to the ask site and storing that somewhere that it can be retrieved on future visits. This would no doubt require changes on the ask side as well.

> I'm REALLY not trying to be negative here, it's just that this problem
> turned out to be the bane of my existence. :)  We solved it by storing
> comments external to the document, keyed off ID attributes, and
> programmatically making sure that every element that could be marked had
> an ID value.  Authors chafed at it, complaining that it made the source
> less readable, but I couldn't think of another foolproof way to do it.

I don't think, at the section level, this would be an additional impost over what we already do. At the paragraph level it would be.

> Eventually it led to a significant number of authors choosing to use a
> format similar to RST instead, (where ID values were even MORE of a
> problem) in order to get better readability.  Which begs the question,
> what about our docs that are already in RST?

These get converted to DocBook XML in an intermediate step, and ultimately are run through the same transforms as the rest of the guides to produce the output. Anything we applied in the transformation for the other guides would apply to these too. As you note identifiers might be problematic as while there are some they don't appear (looking at the HA guide) to be as frequent/consistent - looking at the structure of the existing identifiers in the HA guide it may even be possible to automate generation of these though.

Thanks,

Steve