Open Stack

Id values on each section are required because of commenting. We already programatically require this. ASCII doc also allows this. RST doesn't have this mechanism nor does markdown. 

We are wanting to replace disqus with an id per output HTML page not per paragraph. If people want to ask about or report a bug for a para they can say so in text, no need for fine grained threads.

Chanda Kumar expressed interest in the implementation and he and David Cramer are going to meet soon. Who else is interested in implementation?

I'm interested in notifications and moderation, how are these handled?



Anne Gentle
Content Stacker
anne at openstack.org


On Oct 31, 2013, at 7:58 AM, Nicholas Chase <nchase at mirantis.com> wrote:

>>> 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
> 
> _______________________________________________
> Openstack-docs mailing list
> Openstack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs