Workshop výměny zkušeností mezi techwritery 2018
TW Workshop sdružuje nadšené techwritery z České republiky, aby sdíleli své znalosti, zkušenosti a v neposlední řadě i radost z psaní. Chcete-li se setkat s (nejen) českými techwritery, najít řešení nějaké zapeklitosti týkající se textu nebo třeba nástrojů nebo naopak prezentovat výsledky vaší práce či nový způsob práce, pak jste v naší skupině vřele vítáni. Stejně jako my možná uvítáte, že všichni více méně bojujeme se stejnou hydrou nebo možná větrnými mlýny.
Naše setkání se konalo 14. června v Praze.
Tuto stránku průběžně doplňujeme o všechny novinky, proto ji zkuste sledovat pravidelně.
- Příchod od 9:30,
hlavní program začne v 10:00,
- formát: prezentace (viz níže) + diskuze
- pauza na oběd někde uprostřed,
- konec kolem 17:00
Prezentace proložíme pauzami s kávou a lehkou svačinkou.
Kapacita workshopu je 20 účastníků včetně prezentujících.
Náš workshop nenavštěvují jen češi, proto jsme se rozhodli, že akce bude probíhat v obou jazycích – prezentující se rozhodnou sami, ve kterém jazyce chtějí mluvit (čeština nebo angličtina). Složení publika je obvykle neznámo do poslední chvíle, ale jakmile ho budeme znát, dáme vědět prezentujícím.
Doporučeným jazykem pro letošní workshop je angličtina.
Workshop již proběhl.
Věnovali jsme se následujícím tématům:
Jiri Kosek (xmlguru.cz): CSS Paged Media – Create Beatiful PDFs With Ease – PRESENTATION
Having printed or PDF version of documentation is still important for many users. There are many tools that allow generating PDF output from single source. However, they usually provide generic output with poor design. Customization usually requires expert knowledge of technologies like TeX or XSL-FO – something that is more and more rare. Quite recently it became possible to generate production ready PDF just with CSS – technology that is widely known and easy to use.
Vendula Lucakova (GoodData): SDK DOCs – Developers & Writers in Coop Mode in GitHub – PRESENTATION
Recently we started with SDK docs for our UI. The first public release, or rather what preceded it in our company, was a mess – docs on GitHub, millions of updates, hundreds of pull requests, tens of users. We want to discuss how we survived and how are we planning to stay insane during future releases.
Vendula Ferschmannova (Dativery): Wordpress as a Documentation System – PRESENTATION
Wordpress is the most used publishing platform. More than a half of the Internet use it. Therefore, it makes sense to use it for documentation, too. I decided to give it a try in Dativery. In my presentation, I would like to summarize all pros and cons.
Misha Ramendik (Red Hat): Twice a User, Half a Developer – Documenting Highly Technical Topics – PRESENTATION
Highly technical topics, such as configuration or cloud deployment, present a special challenge to the technical writer. We can not rely on SME input and just edit that, as often was done earlier. Specifications are no longer in vogue at all, and also, we need to ensure the full actual procedure for the customer is covered – while SMEs can see a lot of things as “given”.
The technical writer must form a model of the process that the customer needs to follow. Not just “try running it”, sometimes we need to work with field engineers to make sure we understand the needs. But most importantly we need to understand the logic of everything that is going on, even if it takes significant technical research. We need to cover all the user base with our model, we become “twice the user”.
This model helps us ask many useful questions. Some of these can lead to detection of bugs and late code fixes, others are for Dev/QA SMEs to answer. It is essential that we gain as much understanding as possible before we ask, so the question is taken by Dev to be “from their own side” – we are joining the experts here to ensure we get a full detailed answer (and then filter it down into the text). “To ask a good question you need to know half the answer”. To work well with the developer, the writer becomes half a developer.
Tomáš Raděj (Red Hat): Collaborating With The Community When Documenting an Open-source Product – PRESENTATION
In the Red Hat Openshift Application Runtimes product, we contribute documentation to community projects, and reuse parts of it in our enterprise product. This presentation talks about the workflow, tools, and situations the Red Hat documentation team faces when collaborating with the community.
Marie Doleželová (Red Hat): Documentation on Transition: Feature-based to User Stories, Docbook to AsciiDoc – PRESENTATION
Previously, we produced the documentation that was mainly feature-based and was written in DocBook. Now, we are moving towards docs focused on user stories and written in AsciiDoc. We rewrite the current docs and produce new docs as well. Conversion of docs is quite challenging; various problems need to be resolved. The system of storing metadata has changed as well as the system of publishing.
Milan Navrátil (Oracle NetSuite): Promoting Technical Writing: What to Talk About & How – PRESENTATION
Techies and laymen alike have a lot of misconceptions about what technical writing entails. In this presentation, I'll share some of my favorite metaphors that I use when discussing technical writing and documentation. Also, I'll talk about my approach to spreading the word about the importance and benefits of high-quality technical writing.
Zuzana Lena Ansorgova (CZ.NIC): The Future of Content Delivery – PRESENTATION
Smart cyber-systems will soon require smarter docs. While content development has become efficient, content delivery has been overlooked. Searching in books is no longer efficient for readers, especially with products that are made of hundreds of components made by tens of producers. Readers require a concrete piece of information that is compact and relevant to their current situation. Could this be achieved with ontologic metadata? And how about using the same principle to support documentation maintenance?