Mastodawn

Фильтруй. Переиспользуй. Собирай. Почему DITA — идеальный формат для разработки сложной технической документации

Формат DITA позволяет полностью сосредоточиться на содержании документа и не думать о его оформлении. Кроме того, этот инструмент помогает легко и быстро вносить изменения и дополнения в уже написанные ранее документы. Если с DITA как следует разобраться, то потом написание сложных технических документов существенно упростится. В этой статье я расскажу об основных достоинствах DITA.

https://habr.com/ru/companies/bercut/articles/951260/

#dita #dita_open_toolkit #документация #технический_писатель #пользовательская_документация #xml #форматы_документов #docascode #техническая_документация #bercut

Фильтруй. Переиспользуй. Собирай. Почему DITA — идеальный формат для разработки сложной технической документации

Вспомните свои ощущения, когда обстоятельства заставили вас сменить удобный привычный инструмент на другой, неудобный и неэргономичный. Неважно, что это будет — клавиатура, телефон, отвёртка или...

Хабр

jorge Jan 4, 2024

Hace unos meses me contactaron de una conocida empresa que organiza eventos, charlas, etc en Madrid, Milán, y cuyo nombre empieza por Codemo, proponiendome si quería escribir artículos tech para su plataforma

En un primer momento me vine arriba y les dije que sí casi al momento. Quería escribir sobre #DocAsCode y cómo uso #Asciidoctor y porqué no usar Mierdown ...

Incluso me apunté al canal que han creado con otros autores

Pero luego me he ido viniendo abajo y voy a pasar. Creo que no me apetece por un lado seguir predicando en el desierto y por otro ya tengo mi blog donde escribo lo que quiero cuando quiero y me da (un poco) igual la visibilidad, que es lo único que te ofrecían, porque de pagar en € los artículos ya dijeron que nastideplasti

Paepke Aug 17, 2023

There is vale.sh for writing better docs and linting them. But is there also a good tool to check if the structure is compatible with some kind of a schema? Like containing specific headings and a minimum amount of words as a description. #documentation #DocAsCode

embarc Software Consulting Jun 26, 2023

Wollt ihr mehr über #Methoden, #Vorlagen und #Tools erfahren, die zum Erstellen einer hochwertigen, sich selbst validierenden #Softwaredokumentation eingesetzt werden? Dann hört euch den Vortrag von @sippsack und @dirkmahler auf der #bettercode an. Sie zeigen euch u. a. Ansätze wie #Docs-as-Code, leichtgewichtige Textformate, Ablage in der Versionsverwaltung und die Einbettung in die Build- und Review-Prozesse. 👉
https://archdoc.bettercode.eu/veranstaltung-20915-se-0-lebendige-architekturdokumentation-mit-docs-as-code-jqassistant-und-jmolecules.html

#softwarearchitecture #softwaredokumentation #docascode

betterCode() ArchDoc 2025 - Online-Event für Softwarearchitekten

heise-Konferenz für Softwarearchitektinnen und -architekten: moderne und praktische Dokumentationsmethoden mit und ohne KI. Anerkannten Experten und Diskussion.

betterCode() ArchDoc 2025

Podcast Projets libres Jun 9, 2023

Parlons documentation avec @themr0c, Senior Technical Writer chez Red Hat !

https://smartlink.ausha.co/projets-libres/fabrice-flore-thebault-senior-technical-writer-chez-red-hat

#podcast #IA #nocode #documentation #kubernetes #OpenSource #ansible #freesoftware #rudder #redhat #docascode #antora #fosdem #glpi #obsidian #NoCodeFrance

Fabrice Flore-Thébault - Senior Technical Writer chez Red Hat

Bienvenue dans cet épisode où nous partons à la découverte du métier de rédacteur technique (technical writer) en compagnie de Fabrice Flore-Thébault. Fabrice, après des études d'histoire et de lettres, a fait une rencontre décisive avec le logiciel libre. Son parcours l'a conduit à explorer différents domaines tels que le support informatique, l'administration système et le DevOps. Finalement, il a trouvé sa voie dans la rédaction de documentation chez Red Hat, en tant que Senior Technical Writer. Au cours de cet épisode, Fabrice nous fait part de son expérience et nous dévoile le quotidien de son métier de rédacteur technique. Nous abordons divers sujets, notamment : Les différents types de rédacteurs techniques et leurs rôles spécifiques. Les concepts d'upstream et de downstream dans le domaine des logiciels libres, ainsi que l'automatisation de la génération de la documentation. L'expérience de Fabrice avec Ansible et Kubernetes, et comment ces technologies influencent son travail. Une comparaison entre Asciidoc et Markdown, ainsi que l'utilisation d'Antora dans la création de documentation. Le modèle Red Hat et la manière dont il permet la productisation de logiciels libres. La manière de documenter dans le domaine du No-code/Low-code. L'influence croissante de l'intelligence artificielle sur le métier de rédacteur technique. Pour en savoir plus sur Fabrice : Le profil LinkedIn de Fabrice Flore-Thébault (https://www.linkedin.com/in/fabriceflorethebault/) Le profil Github de Fabrice (https://github.com/themr0c) Les conférences données par Fabrice (https://flore-thebault.com/slides/) La conférence de Fabrice sur la création d'un pipeline de documentation avec Antora (https://flore-thebault.com/slides/2023-antora-pipeline/) Le site de Red Hat (https://www.redhat.com/fr) Les outils dont parle Fabrice ou qu'il souhaite partager en plus : Podman Desktop (https://podman-desktop.io/) , dont Fabrice est le technical writer attitré Antora (https://antora.org/) Asciidoctor (https://docs.asciidoctor.org/asciidoc/latest/) IntelliJ Asciidoc plugin (https://intellij-asciidoc-plugin.ahus1.de/docs/users-guide/index.html) Obsidian (http://obsidian.md/) Markdown Extended (MDX) (https://mdxjs.com/) Chigaco Manual of Style (https://www.chicagomanualofstyle.org/home.html) Red Hat supplementary style guide for product documentation (https://redhat-documentation.github.io/supplementary-style-guide/) Rudder (https://www.rudder.io) GLPI (https://glpi-project.org) Ansible (https://www.ansible.com/) Kubernetes (https://kubernetes.io) OpenShift (https://www.redhat.com/fr/technologies/cloud-computing/openshift) Meetup Continuous Documentation Regulars (https://www.meetup.com/fr-FR/continuous-documentation-regulars/) Les liens pour les outils No-code/Low-code : La commaunté No-code France (https://nocode-france.fr/) Documenter du nocode avec ncScale (https://www.ncscale.com/)

Fabrice Flore-Thébault - Senior Technical Writer chez Red Hat | Projets libres !

Luc Sorel-Giffo Feb 12, 2023

0.7.1 release of #py2puml 🎉

Several improvements of the generated #PlantUML syntax:
- use the 'namespace' instructions to group and nested datastructure definitions, to illustrate the codebase structure
- complex compound types (like Dict[Tuple[str], List[SomeClasse]]) are handled

Py2puml is a #DocAsCode tool, which generates a class diagram from your #Python app codebase.

- try it out: https://pypi.org/project/py2puml/
- give some feedback (issues and ⭐ are appreciated 🙏): https://github.com/lucsorel/py2puml

py2puml

Generate PlantUML class diagrams to document your Python application.

PyPI

Luc Sorel-Giffo Feb 7, 2023

✨ 1st release of #pydoctrace 🎉
Trace #Python code execution with a decorator to view the corresponding sequence diagram in #PlantUML syntax.

#DocTracing generates documentation from real-life code execution and illustrates how the codebase is executed and organized. It helps discussing architecture or teaching algorithms. #DocAsCode

- try it out: https://pypi.org/project/pydoctrace/
- give some feedback (issues and ⭐ are appreciated 🙏): https://github.com/lucsorel/pydoctrace

pydoctrace

Generate sequence diagrams by tracing Python code execution

PyPI

Luc Sorel-Giffo Jan 12, 2023

Version 0.6.1 of #py2puml is released 🎉

This #Python library generates the class diagram of the data structures defined in your codebase. This new version handles class having digits in their names.

#DocAsCode helps documenting the codebase, understanding and maintaining it with better insights.

https://pypi.org/project/py2puml/