search

roboticslab-uc3m / questions-and-answers

A place for general debate and question&answer
https://robots.uc3m.es/developer-manual/appendix/repository-index.html
2 stars 0 forks source link

Generate FAQ gitbook #10

Closed jgvictores closed 6 years ago

jgvictores commented 7 years ago

Generate FAQ gitbook from relevant closed issues of this repository.

jgvictores commented 7 years ago

https://www.gitbook.com/book/roboticslab-uc3m/qa

jgvictores commented 6 years ago

Among this line, a script to port closed issues (not invalid) to .md sounds feasible. Would it be worth the effort?

David-Estevez commented 6 years ago

IMHO this is one of those occasions in which a human synthesizing the information contained in the closed issue is required. Otherwise that book would be equivalent to a search among the issues of this repository.

jgvictores commented 6 years ago

Otherwise that book would be equivalent to a search among the issues of this repository.

Which is one of the reasons I have also been doubting if this issue should be labeled invalid. :-)

Let's turn this into a question! Is human synthesizing the information contained in the closed issues of this repository worth the effort?

David-Estevez commented 6 years ago

In my opinion, doubts are usually due to some misleading or missing documentation and, when they happen, docs should be fixed. It is also important to make these fixes visible instead of buring them in a repository.

Doubts may arise from very different repositories and contexts, and this a quite generic place to store them all. Therefore I think that users and developers will benefit if the results of each closed issue is documented at the place or context that generated that particular doubt.

But this is my particular view, and I would like to read other opinions to know what do the rest of the team think about this and their ideas.

PeterBowman commented 6 years ago

Have you ever considered using the Wiki tab (between Projects and Insights)? It could be a good place to collect repo-related stuff regarding recurrent issues and their solutions, FAQs, guides, etc.

jgvictores commented 6 years ago

@David-Estevez Agreed that issues should be moved as close as possible to scope of repository, but still think there are general questions so this repo has a reason to be (in addition to a generic place for newbies).

@PeterBowman I like GitBook because it is synced with the repo. Wiki feels like a yet another repo (in fact has its own URL) and that really does start to feel like too many repos.

jgvictores commented 6 years ago

Almost distiguishing 3 types of issues in this repo (first and second are similar, but I wanted to distinguish them, because the first group could look like a motivation for a FAQ gitbook at first glance, but not on second thought):

  1. Questions that once answered should become part of https://github.com/roboticslab-uc3m/best-practices (examples: #29 , #14 ...) -> no reason for a FAQ gitbook.
  2. Questions that should become part of a different repository (mostly moved already). -> no reason for a FAQ gitbook.
  3. Tasks that are very horizontal to the organization, such as #2 (Major code reorganization among repositories). -> no reason for a FAQ gitbook.

In consequence, and thanks to your contributions, I am considering the answer is no and closing this issue. Please reopen if you think elsewise!!!

jgvictores commented 6 years ago

Comment on small outliers:

jgvictores commented 5 years ago

Update: best-practices is now https://github.com/roboticslab-uc3m/developer-manual so this makes even more sense.