Open Stack

Hi Stef,

Regarding the versioning and linking questions to the paragraphs,
I think there will be a limitation that once the paragraph changes,
any questions will be detached.

We could track content of paragraphs
by remembering hash values of their content.

We could still display those questions and maybe give an option
to re-attach them to the corresponding paragraphs.

Best regards,
Evgeny.




On Thu, Oct 31, 2013 at 8:02 PM, Stefano Maffulli <stefano at openstack.org>wrote:

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



-- 
Askbot
Valparaiso, Chile
skype: evgeny-fadeev
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20131031/a13f0cb2/attachment-0001.html>