[Openstack-docs] Integrating Ask OpenStack in docs

Nicholas Chase nchase at mirantis.com
Thu Oct 31 12:58:03 UTC 2013


>> 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?

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

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?

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.

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?

As always, YMMV.

----  Nick



More information about the Openstack-docs mailing list