Novo plugin de documentação em desenvolvimento

Anúncios
,
1

Recentemente, disponibilizamos nosso novo plugin de documentação para testes e feedback. Este plugin foi projetado para aprimorar a navegação e a acessibilidade da documentação hospedada no Discourse, proporcionando uma experiência mais acessível e amigável para todos os usuários. Observe que este plugin ainda está em desenvolvimento.

O desenvolvimento deste plugin decorre de nosso esforço contínuo para melhorar a documentação, que já foi aprimorado por uma nova barra lateral. O trabalho na barra lateral lançou as bases para uma experiência de documentação muito aprimorada, e o novo plugin se baseia incrementalmente nesse trabalho.

:boom: O novo plugin em ação

O plugin está atualmente ativo e impulsionando a documentação em nossa documentação oficial do Discourse. Convidamos você a explorar seus recursos e compartilhar suas experiências conosco. Seu feedback é inestimável para nos ajudar a refinar e aprimorar o plugin.

Os principais recursos incluídos no novo plugin são:

  • Configurações para definir quais categorias são usadas para documentação
  • Uma nova barra lateral de documentação preenchida por tópicos de índice dentro de cada categoria
  • Dois novos relatórios para ajudar a manter a integridade e a precisão dos tópicos de índice

Com mais em desenvolvimento enquanto aprimoramos continuamente os recursos disponíveis.

O novo plugin está disponível para download e instalação hoje: Discourse Doc Categories

:electric_plug: Transição do plugin Discourse Docs

À medida que inovamos e avançamos, desativaremos nosso plugin mais antigo Discourse Docs plugin. No entanto, você pode ter certeza de que continuaremos a apoiá-lo até que o novo plugin esteja totalmente pronto para um lançamento generalizado. Também garantimos que o novo plugin redirecionará os URLs do plugin antigo, portanto, a troca não resultará em nenhum link quebrado.

Observe que o novo plugin ainda está em seus estágios experimentais. Embora nosso objetivo seja fornecer uma experiência perfeita, pode haver algumas áreas que exigem mais aprimoramento. Seu feedback construtivo será crucial para seu sucesso.

:speaking_head: Conte-nos o que você pensa

Agradeceríamos suas opiniões, experiências e feedback. Sinta-se à vontade para compartilhar suas experiências e quaisquer insights que você coletar ao usar o novo plugin de documentação, seja navegando pela documentação no Meta ou instalando o plugin em seu próprio site.

Nosso objetivo é moldar uma melhor experiência de documentação para toda a comunidade Discourse, portanto, todo feedback é bem-vindo!

Detalhes completos do plugin disponíveis aqui:

13 curtidas
2

Alguém precisa atualizar o readme. E talvez atualizar as regras de lint para evitar que isso aconteça, embora haja uma questão de ovo/galinha.

Parece que também poderia ser ótimo para usar o Discourse como um LMS. Para isso, seria bom poder alternar qual categoria era uma categoria de documentação, embora haja uma boa chance de que apenas usar permissões para dar aos usuários acesso a certas categorias seja suficiente para que funcione.

8 curtidas
3

Boa observação sobre a URL - acabei de enviar um PR para adicioná-la.

Parece um caso de uso interessante para isso, e consigo ver como funcionaria muito bem!

6 curtidas
4

Esta é uma melhoria fantástica em relação ao plugin original de Documentos/base de conhecimento. Até agora, parece muito fácil de usar.

Testar no Meta é definitivamente um grande ponto positivo, pois as categorias de documentação aqui podem dificultar a localização de coisas anteriormente.

5 curtidas
5

Ouso perguntar por uma ETA? Ou seja, quando este plugin será considerado menos experimental e mais em estágio beta, ou talvez até mesmo um candidato a lançamento inicial? Sei como é difícil prever o futuro, então ficarei feliz com qualquer estimativa aproximada, por mais imprecisa que seja. :wink:

Atualmente, estou explorando o Discourse como uma ferramenta no trabalho, exatamente porque ele parece ser capaz de oferecer uma boa mistura de discussões comunitárias e um espaço compartilhado para documentação. Onde é tão fácil escrever documentação quanto postar um comentário em um tópico.

Portanto, o recurso de tópico wiki por si só é ótimo, é claro, é um ótimo começo. Este plugin, no entanto, adiciona coesão ao conteúdo dos tópicos, o que acredito ser essencial para a experiência do usuário da documentação.

A categoria de Documentação em meta.discourse.org agora parece um site de documentação estruturado de verdade, em vez de apenas alguns tópicos aleatórios do fórum que por acaso compartilham uma categoria e por acaso descrevem como o Discourse funciona.

Então, continuem o bom trabalho. Obrigado!

1 curtida
7

Eu gosto muito! A documentação e os Discursos se encaixam muito bem.

Vocês têm planos de habilitar a indexação de tags além das categorias?

8

Eu acho que o estágio em que estamos agora é “a beleza (ou a falta dela) está nos olhos de quem vê”

É experimental no sentido de que existem problemas de UX conhecidos, especialmente para os responsáveis pela manutenção da documentação e, em particular, dos índices, mas é completamente seguro de usar em produção.

Tudo isso para dizer que agradeceríamos muito seu feedback se você o experimentar e o testar.

Não temos nenhuma ETA neste momento para melhorar os problemas conhecidos de UX com a manutenção de índices, mas o feedback das pessoas que o utilizam pode ajudar a direcionar o caminho.

Não, isso não é algo que tenha surgido em nenhum lugar ainda. Você pode compartilhar um pouco mais sobre o que está pensando ou por que isso seria útil para você?

4 curtidas
9

Sobre isto: Se você estiver em uma categoria de documento e fechar uma janela de chat não em tela cheia, a navegação do documento também é “fechada” e a barra de navegação normal é exibida novamente. Enquanto reproduzia no meta, também notei que clicar na bolha de chat (canto superior direito do cabeçalho) também fecha a navegação do documento. Espero que ajude!

3 curtidas
11

Obrigado por relatar isso - consigo reproduzir, então registrei isso e incluiremos no próximo trabalho de desenvolvimento aqui.

3 curtidas
13

Isso me lembra de uma coisa sobre o Discourse como projeto, que não é realmente ideal para mim como usuário. O fato de o projeto não usar um rastreador de problemas público adequado para bugs e planejamento.

Por exemplo, quando leio a resposta de Hugh, meu gerente de projeto interno imediatamente levanta a questão: onde, onde isso foi registrado?. Eu sei, meu gerente de projeto interno é uma criaturinha curiosa, não é? :slight_smile:

Suponho que usar meta.discourse.org como rastreador de problemas dá ao projeto uma oportunidade de “dogfooding” o Discourse. E todos os outros rastreadores de problemas têm suas próprias falhas, então é uma chatice ter que escolher um. Mas para mim, o Discourse - embora seja excelente como fórum para perguntas e discussões - é muito deficiente como rastreador de problemas. Para esse propósito, ele carece de categorização eficaz, informações sobre versões afetadas e de destino, números de problemas, priorização, meios eficazes para filtrar problemas por status, idade, prioridade, produto ou componentes, e uma boa maneira de apresentar um roteiro para um recurso ou para o produto como um todo, entre outras coisas.

Bem, estou divagando. E ainda não contribuí com uma única linha de código, relatório de bug ou solicitação de recurso, então quem sou eu para reclamar. :wink:

Então, novamente, obrigado a todos pela grandiosidade do Discourse. E desculpem o semi-desabafo.

E de volta ao tópico, ótimo saber que as Categorias de Documentos do Discourse, embora ainda não polidas, são consideradas arquitetonicamente estáveis. Verificarei se consigo instalá-lo em minha instância hospedada do Discourse e, se sim, tentarei retornar com feedback. Obrigado!

6 curtidas
14

Eu esqueci de responder aqui. Obrigado pelo seu acompanhamento.

Eu entendo que #wiki poderia se encaixar em diferentes categorias como suporte à comunidade dev, e é melhor mostrar dados com base nos interesses dos usuários.

Enquanto isso, mostrar esses wikis organizados em docs (link na barra lateral do wiki) parece ótimo.

1 curtida
15

Usamos o Discourse como rastreador de problemas. Melhor dizendo – eu tento forçar minha equipe a usar o Discourse como rastreador de problemas :slight_smile: E um wiki, e um fórum, e documentação… Suspeito que a equipe do CDCK tenha outro site “secreto” do Discourse onde eles rastreiam suas coisas internamente, usando alguns plug-ins interessantes, que ninguém tem…

Não importa quão bom seja o rastreador de problemas aqui, a comunidade não pode ser comparada a nada mais que eu conheça. No final, são as pessoas que desenvolvem o software, não a tecnologia por trás dele. E elas são demais! :metal:

E eu gosto muito do plug-in de documentação. :heart:

Agora, com todos os meus elogios, seria possível aprovar meu PR? :smiley:

5 curtidas
16

Você viu a resposta do Gerhard naquele PR?

3 curtidas
17

Nós temos outro site que usamos internamente e é realmente assim que rastreamos muito do nosso trabalho. Mas não o fazemos com nenhum plug-in secreto.

Principalmente, usamos convenções, como uma categoria para “a fazer” e um conjunto padrão de algumas tags para um tipo de priorização agora/próximo/depois, juntamente com o plug-in de atribuição para esclarecer a propriedade.

Isso também permite que o componente de tema kanban funcione, mas nem todos usam essa visualização.

É bastante fluido, não um rastreador de problemas altamente opinativo, mas funciona bem para nós.

Eu poderia compartilhar mais detalhes alguma hora…

6 curtidas
18

Não! Minha culpa. Corrigido. Obrigado pelo aviso.

3 curtidas