Open Stack

On 10/30/2013 05:56 PM, Stefano Maffulli 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.

I think this is the most interesting bits of all. What I think would be
very useful is to have a place *on the documentation page* for people to
express doubts and ask questions. So, a use case would be of a user that
goes to http://docs.openstack.org/user-guide/content/cli_openrc.html and
has a doubt about it. The user notices a place at the bottom where she
can ask a new question with her doubts. The new question would be
connected to the related page only, visible only on
http://docs.openstack.org/user-guide/content/cli_openrc.html and on
https://ask.openstack.org of course. If there are other questions
connected to that page, all of them would have to be shown (collapsed?)
before the 'ask a new question'.

What's not clear to me is how to manage versioning of documentation.
Let's assume that a question is related to
http://docs.openstack.org/user-guide/content/cli_openrc.html and that
page gets fixed/updated making (some, if not all) questions obsolete/not
relevant: how to manage the obsolescence? And more deeply, how to manage
the link between individual pages and questions?

>> 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 would love to work at the paragraph level with questions (like Google
Docs comments) but I'm not sure how we can achieve that by keeping the
current docs authoring and build workflow. Any ideas?

>> It could be useful to link authors of the page with the profiles in
>> the Q&A system, if they exist, in order to notify the authors of the
>> new questions.

Can the people interested in answering questions about documentation
would get a notification of a new question or updates to old questions
(comments or answers) using the standard notification system of Askbot
(subscribing to a tag or something similar)?

>> On the "regular" forum question pages there would be "backlinks" to
>> the relevant doc pages.
>>
>> Questions may be assigned/reassigned to one or more doc pages.

This would be cool, too, a way to manually curate/enrich the question
like we do with bugs. Which brings us back to the question above: how to
link a question/answer and the originating page with its version?

/stef

-- 
Ask and answer questions on https://ask.openstack.org