24

Apareceu uma nova funcionalidade no Stackoverflow gringo chamada Documentation, veja:

inserir a descrição da imagem aqui

Eu gostaria de saber o que é e se vamos ter aqui no SOpt também?

=D

1

3 Respostas 3

20

Se vamos ter aqui eu não sei, duvido que a própria SE saiba no dia de hoje (ver data abaixo).

A SE viu uma "falha" no mecanismo atual e uma necessidade existente. O Q&A é ótimo para dúvidas específicas. Mas não é um formato tão bom para montar documentação de APIs e outras coisas. E ter uma forma colaborativa de montar documentação é algo muito interessante para todos, incluindo produtores de API e também para o próprio Q&A da SE que muitas vezes precisa linkar para uma documentação. Documentação que não existe, que está desatualizada, que deixa de existir, pelo menos naquele endereço linkado, entre outros problemas.

Por que não usar o know how adquirido com a gamificação do Q&A para fazer algo semelhante para a documentação? Daí nasceu o SO Docs.

Parte do mecanismo é o mesmo ou bem parecido, parte é novidade, mas lembra um pouco a dinâmica que já conhecemos.

A ideia dele é ter aquelas páginas de documentação mesmo. Pelo que percebi terá textos, mas o principal será o uso de exemplos de fazer alguma coisa. Receitinha de bolo.

A tendência é que vários projetos o adote com auxiliar ou deixe toda documentação no SO Doc.

É útil e ajudará evitar duplicatas no Q&A. Acho que a tendência é o Docs ter mais "o que fazer" e o Q&A ter mais o "porque fazer".

Gosto da ideia de ser mais colaborativo que o Q&A. Vamos ver o quanto dará certo. Seria bom. Está no caminho certo, aparentemente.

Tomara que dê muito certo e depois venham outras variantes para outros tipos de conteúdo que não se encaixam nem no Q&A, nem no Docs.

9
  • 7
    Pois é, várias respostas linkadas para o mesmo pedaço de documentação = bom mecanismo para encontrar perguntas duplicadas (eu tentei fazer isso usando links do JDK na época que o SOen estava promovendo a faxina). Tomará que em algum ponto, quando o Documentation estiver mais maduro, promovam um mutirão para linkar respostas antigas com documentação (seria lindo para limpar o site) Commented 21/07/2016 às 20:32
  • 1
    Será que poderia ser mais específico? Li ambas respostas e ainda não entendi como ele será utilizado. Será com base nas respostas que o site já contém? Possuo criar um DOC de uma API pessoal no site? Seria possível fazer um breve esclarecimento do que é e não como surgiu? Falo isso pois eu senti uma dificuldade em entender essas questões.
    – Randrade
    Commented 22/07/2016 às 14:32
  • 3
    @Randrade mostrando em termos do que já conhece, é isto aqui: msdn.microsoft.com/en-us/library/… Só que será criado colaborativamente e terá gamificação. Parece que está havendo algum controle inicial (pelo que entendi só pode criar novas tags no Docs se ela já existir com expressividade no Q&A), mas pode mudar depois para você criar uma documentação da sua API (talvez desde que tenha um mínimo de demanda no Q&A). O fato que nem eles sabem ainda totalmente como vai funcionar. O beta está servindo para ver o que funciona ou não.
    – Maniero Mod
    Commented 22/07/2016 às 14:39
  • 1
    Mesmo depois muita melhoria ainda virá. Obviamente eles serão mais cuidadosos no começo. Qualquer coisa muito detalhada que se fale agora pode ficar defasada. Tem alguma dúvida específica? Já leu o blob? blog.stackoverflow.com/2016/07/…
    – Maniero Mod
    Commented 22/07/2016 às 14:41
  • 1
    Obrigado por esclarecer. Eu li o blog sim, mas ele me deu mais dúvidas ainda, por isso as perguntas. Só mais uma dúvida... No blog e na documentação, o "show" são os exemplos. Esses exemplos são perguntas já contidas no SO ou são "recriados" no DOC?
    – Randrade
    Commented 22/07/2016 às 14:43
  • @Randrade acho q não, pelo que vi vc cria um tópico e posta o conteúdo ensinando e explicando alguma coisa.
    – gato
    Commented 22/07/2016 às 14:48
  • @Randrade não sei de que show está falando. O Docs é algo de certa forma separado e diferente. É uma coisa mais estruturada, é para criar páginas de documentação como essa da MS que eu linkei aí em cima. Aí vc pode ter algo mais completo, mais atualizado (mantendo diferença pra versões), fica garantido que sempre estará disponível. Não é algo novo, é só uma forma nova de fazer, como aconteceu com o Q&A era. Eles terão vida própria. O que certamente vai acontecer é as pessoas linkarem nas suas respostas do Q&A pra eles sempre que possível.
    – Maniero Mod
    Commented 22/07/2016 às 18:11
  • @bigown Valeu pela explicação. Só explicando, utilizei o termo "show" pois o mesmo está no link do blog sobre a notícia.
    – Randrade
    Commented 22/07/2016 às 18:16
  • Exemplo de uso de integração entre Q&A e Docs já aqui no SOpt: pt.stackoverflow.com/q/142150/101
    – Maniero Mod
    Commented 22/07/2016 às 20:07
7

O bigown explicou muito bem:

A SE viu uma "falha" no mecanismo atual e uma necessidade existente. O Q&A é ótimo para dúvidas específicas. Mas não é um formato tão bom para montar documentação de APIs e outras coisas. E ter uma forma colaborativa de montar documentação é algo muito interessante para todos, incluindo produtores de API e também para o próprio Q&A da SE que muitas vezes precisa linkar para uma documentação.

A primeira parte, sobre nós ainda não sabermos se teremos aqui também, é verdade. Infelizmente, há uma série de coisas que ainda não resolvemos sobre como manter os sites internacionais funcionando. Não são problemas fáceis de resolver e adicionar mais coisas internacionais - seja Docs, Jobs, Teams, etc - só dificultaria a solução dos problemas.

Continuamos tentando consertar todos esses problemas, mas leva tempo. E até lá, não temos como dar uma resposta mais exata do que "provavelmente, um dia".

Atualização

Stack Overflow Docs é o tema do segundo Estado da Pilha. Eu entro em mais detalhes sobre o que atravanca a habilitação do Docs no SOpt, como a tradução do site precisa ser resolvida se quisermos que ele continue se expandindo.

Tentei ser o mais claro o possível, considerando que é uma situação pra qual não temos resposta, e espero que possa ajudar vocês a entenderem melhor a situação do Docs. Além disso, estamos sempre abertos à sugestões. Se você tem alguma ideia do que pode ser feito pra melhorar o site, os comentários aqui embaixo (ou no blog) estão abertos!

9
  • 4
    Será que poderia ser mais específico? Li ambas respostas e ainda não entendi como ele será utilizado. Será com base nas respostas que o site já contém? Possuo criar um DOC de uma API pessoal no site? Seria possível fazer um breve esclarecimento do que é e não como surgiu? Falo isso pois eu senti uma dificuldade em entender essas questões.
    – Randrade
    Commented 22/07/2016 às 14:31
  • Será documentada apenas APIs ou outras tecnologias e ferramentas também serão documentadas?
    – gato
    Commented 22/07/2016 às 14:50
  • 4
    @DenerCarvalho APIs, linguagens, programas, bibliotecas... O escopo é tão grande, se não maior, que o do SO
    – Gabe Staff
    Commented 22/07/2016 às 15:12
  • A pergunta e as respostas são de julho. Houve atualização sobre o assunto? Commented 18/11/2016 às 12:20
  • @TomásBarcellos Sim. Vai ser o assunto do Estado da Pilha desse mês. Hoje mais tarde eu tenho o link.
    – Gabe Staff
    Commented 18/11/2016 às 14:18
  • 1
    @TomásBarcellos Segunda-feira, na verdade
    – Gabe Staff
    Commented 18/11/2016 às 15:59
  • 1
    @TomásBarcellos Atualização feita!
    – Gabe Staff
    Commented 21/11/2016 às 18:50
  • 1
    @Gabe cada vez que você edita esse post, eu venho correndo achando que o docs está disponivel pra gente kkkk
    – user28595
    Commented 21/11/2016 às 20:23
  • @diegofm Se serve pra acalmar seu coração, quando o Docs for disponibilizado, o anúncio vai ser feito separado, e não com um update aqui. Só lembrando que não há previsão nenhuma
    – Gabe Staff
    Commented 21/11/2016 às 21:14
5

Eu gostaria de saber o que é e se vamos ter aqui no SOpt também?

NÃO

O Documentation foi um experimento feito pelo SOen que falhou e será desligado no dia 08/08/2017.

2

Você deve fazer log-in para responder a esta pergunta.

Esta não é a resposta que você está procurando? Pesquise outras perguntas com a tag .