Create FAQ section

[simonseyer]

This page should list questions, that are important for the concept of ZUKS and the future development.

Questions are prepared by ZUKS and first answers are written, before this page is launched, but there still could be open questions. The page should be a working document, where interested people could watch the progress of the concept and add there own questions.

I propose the following structure:

1. Question Text? 
Edited at: xx.xx.xxxx, asked by: ZUKS
Answer:
Lorem ipsum.

2. Question Text? 
Edited at: xx.xx.xxxx, asked by: xxxxx
Answer:
Lorem ipsum.

Add your own question:
________________________________________ |Submit|

Proposed features

• Submit form for everyone with fields in the following order
  1. Question
  2. Name / Pseudonym (optional)
  3. E-Mail-Adress to receive updates to the submitted question (optional)
  4. Capatcha ?
• Notification for ZUKS admins on submitted questions
• Versioning of the questions and answers
• Each question has a static link
• (Automatic Twitter posts on update)

  Proposed implementation

• Create a new GitHub repository for the FAQ
• Create a Markdown file for each question
• Check out the repository in the website folder and create a GitHub hook that triggers a pull on the webserver
• On each pull of the FAQ repository a html file is rendered, which is integrated in the FAQ page in django
• When a user submits a new question, a new markdown file is created and pushed to the repository. If the user submitted a mail address, an entry with the mail address and the markdown file is stored in the database. (Because the mail should not be public available)
• In the commit hook on the webserver, it is checked if a file/question was updated where a mail address exists for and a mail is sent.

With this implementation, a versioning is ensured. The admins could be notified by GitHub, when a new question is submitted/committed. GitHub's Pull Request feature could be used, which allows a peer review of the answer and a discussion, before it is visible on the website.

[simonseyer]

@monofox what do you think?

[monofox]

FAQ brings facts in short phrases in a good way. So the idea is good.

I would prefer if we don't use captchas. Meanwhile it is no problem anymore for the bots to read these. And it is not accessibly -> this is a very important point! Of course, without any check we are a very easy target for spam. But this type of problem is also given with captcha. E.g. person ask a similiar questions with is already in the list - or questions which are not relevant to the project.

So your approach for the review is good.

Why you want to display the "asked by"? I think it is irrelevant and makes the FAQ big (applies also to "Edited at"). The date is easily accessible through git in that case.

Also i would configure the FAQ repo as sub-project of the website repo.

Conclusion: i support your feature request!

[simonseyer]

No capatchas: Ok, sounds reasonable.

Review: This review was just intended for our answers, not for questions. It could also be done for questions by creating pull requests for each question submitted (easier for us), but then we have to explain, why the question is not visible directly. @Quizzer: What do you think?

Asked by: My intention is to show which questions we created and which are created by the community. In my opinion it's a public way to say 'thank you' for contributions.

Edited at: Could be skipped. On the other hand, when an appropriate style is applied to these two texts, the size aspect should be negligible.

sub-project: Do you mean the submodule functionality in git?

[monofox]

sub-project: yes, i mean submodule - is a nice feature ;) Asked by: Reasonable, but is that the right way? What is if the question is asked by multiple person? You want to display all?

[simonseyer]

Asked by: I would show the person, wo asked the question first. All other would get a message, that the question was asked before (when a mail address was provided). If the new question is integrated into an old question, I would show a list of persons (really small). Do you have a better alternative in mind?

An additional idea: allow a twitter handle instead of a mail address.

[monofox]

Whats about listing all contributed person in one list instead of associating them to specific question? The advantage would be, that it is not limited to the questions and the FAQ is clean and easy to read.

[simonseyer]

Sounds good.

[Quizzer]

On the whole i do support the FAQ secton as it is presented here. Asked by: Still i do not get how a list of participants could replace the 'asked by' of each question. Remember that the main intention of this field was to indicate whether a single question is a community based one or originates from ZUKS. And this feature seems important to me. Review: As long as it makes it easier for us i would prefer pull requests for each question. Provided that there is a hint for the user "Thanks for your question. We will check and answer as soon as we can", I do not see a problem in not publishing the question immediately.

[monofox]

@Quizzer Review: I appreciate this proposal. Asked by: But why does it seem to be important for you? I don't see any advantage or important thing of it. I don't know at the moment which questions will be "asked" by ZUKS itself, but why should they have another weight than the community driven questions? Mostly these questions will be asked by the community in the same way if we would not publish our own created questions.