Generate FAQ gitbook about questions-and-answers

[David-Estevez]

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]

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

[jgvictores]

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

[jgvictores]

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]

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]

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]

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

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]

Comment on small outliers:

• #28 (How can I program... by demonstration) could go in https://github.com/roboticslab-uc3m/teo-software-manual but maybe deserves a more generic software manual or tutorials repo.
• More outliers could be #27 but that could actually go upstream to yarp.

[jgvictores]

• Questions that once answered should become part of https://github.com/roboticslab-uc3m/best-practices (examples: #29 , #14 ...) -> no reason for a FAQ gitbook.

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