Techwriting_journal

This is my own journal covering my techwriting adventures.

Lexicon
Tools
1. Node.js + VSC
2. Docs to MD
Notes
1. Emojis
Documentations
1. Ones that I have read and liked
2. Ones that I have write and I like
  1. Applifting test
Learning

Lexicon

Tools

Node.js + VSC

Download Node.js and Visual Studio Code (my go to editor). For Node.js, I use the Node.js Modules Intellisense and Node.js Exec.

Ngrok

A tool to route localhost to internet (web testing) ./ngrok http 80

Notes

List of emojis supported by Github

Documentations

As painter needs to see beauty, writer needs to read good stuff.

Ones that I have read and liked

Ones that I have write and I like

This was a test documentation to see, if I can be a techwriter. I spent around 3 hours and 15 minutes on it (this includes research, writing and creating requirements). The biggest challenge was to turn .md to .pdf. I have used three methods: (1) online tool to do so (which had issues with images), (2) GRIP (which made images to work, but destroyed anchors) and (3) pandoc (which made some mess with the anchors but images worked nicely)

+ I like how consistent it is, it was first .md file I am proud of.

- The GIFs did not work in PDF at all, changing .md to .pdf is tricky

Learning sources

This is my personal collection of resources I have learned from. Feel free to browse my personal notes 😏

Courses

When I find a nice online course, I try to take it. The ones with ✅ are the courses I complited.

Technical Writing One

Technical Writing Two

Websites

This is a list of websites I have read in order to understand.

Berkeley how to write

Short and simple guide, mainly academically oriented.

Write the docs

Great community (Slack), template which can in certain projects be like 90 % make most of the job for you and resources over resources.

Tom preston

Interesting idea of README driven development for small project purposes, however, I don't see the scalability of this approach (since more advanced projects are more than just a README.md). -> strong stressing of KPIs and keypoints.

TechwriterToolkit

Interesting list of books that you could read to improve your documentations.

Sohamkamani

A guide the empathises heavily that descriptions should be short, code should be problem solving and that documentation should contain examples.

Divio

This terminology splits documentation into tutorials, how-to guides, technical reference and explanation -> and each of the types has their own motives and goals. Tutorials are learning oriented, how-to are problem oriented, explanations are understanding oriented and reference are information oriented. However, I would say that the dev are not interested in my terminology, they care about solving their issues.

Books I have read

As the title suggests, this section covers books I have read. If you can, toss a coin to the author, friend of techwriting. (But I understand if you can not)

Andrew Etter: Modern Technical Writing

Short book which is like gateway drug for techwriting: explaining the basics of techwriting, basic of markdown, restructured Text and Asciidocs (the difference between them) and talks about some principles.

TAKE AWAYS: Who do you write for?, Don't explain what API is in guide where you are integrating APIs, MD is good but it doesn't have many tools (like tables), so Asciidocs are sometimes the right tool.

Abby Covert: MESS

An interesting book on how to "organise" things into objects that are in locations and spaces and user affects them via interface. They are in larger groups structures which are organized in systems and ecosystems (more systems together). Language matters (must be clear and used by all parties) -> every person making sense of mess does an ontology (lexicology of meanings). Become an Information Architect by understanding with who I am sorting this mess. Use maps (diagrams) to communicate your point across and to build a taxanomy (classifications)

To control your vocabulary:

Create a list of terms to explore.
Define each term as simply as you can.
Underline words within your definitions that need to be further defined, and define them.
Document the history, alternatives, and myths associated with each term.
Review your list of defined terms with some of your users. Refine the list based on their feedback.
Create a list of requirements that join your nouns and verbs together.

TAKE AWAYS: Designing with, not for. Write as simply as possible (you want to get your point, not flex vocabulary), there is no right or wrong the intent matters. Set goals like this. More on IA

John R. Kohl: The GlobaL English Style Guide

The Global English Style Guide is a collection of rules. These rules improve your texts in numerous ways. The first improvement is understandability. The second improvement is how translatable your text is. Last, but not least improvements is a standartized way to approach writing.

TAKE AWAYS: Be as simple as I can. Don't do long sentences. These sentences can confuse non-native readers. If you are creative enough, there is always good sounding alternative to any sentence.

Vidoes I have seen

In this part, I keep notes on various online videos I have seen.

Zuzana Lena Ansorgová: Jak začít dokumentovat

Talk on the absolute basics of techwriting, from the concepts and tools (LaTeX) to tag languages and text publisher. MD is too simple for complex databases. How to show documentation for user(based on their level - the idea of inteligent content delivery(https://blog.nic.cz/2017/11/01/tcworld/ -> https://www.plusmeta.de/#software)) Sphinx is good for complex things. Good starting point.

TAKE AWAYS: Tekom group Certification, think about your writing. MD is limited (but works for small scales). Think how do you deliver content, what is tag languages.

Zuzana Lena Ansorgová: Dokumentování software podle jeho životního cyklu

Talk on whole spectrum of documentations, the difference between process (in house) and product documentation (for end user (can be user, admin, dev or anyone)), good documentation always works with data from business/system analysis (to know key terms, conception (read Concept of Operations) and SRS (software, Requirements and specifications)) for better understanding. Think about how people will use your product (how does it work, what does it need, how to interact with it and more) and write for different levels of users (new wants basic understanding, advanced wants full reference (pro tip, add metadata and navigation to your documents to make them UX friendly))-

TAKE AWAYS: Always try to get as much information as I can, sort it to make it digestible and think for who this documentation is (is it inhouse, is it for outside? What does this text mean?)

Ellie Farrier: Wild Geeks: Poetry in the Digital Age

Interesting talk that emphatises how writing is universal and how even poetry can help with documentations. This resonanted with me since I like to write haikus (just 17 syllables to create image) and this limited space is something that just makes sense in case of docs.

TAKE AWAYS: Think of form, think outside of the box, techwriters role is to share knowledge, poet shares feeling.

Kayla Lee: The Super Effective Writing Process of Grammy-winning Artists

Talk on sharebility of writing as process. At its root, Techwriting is just writing and can hugely benefit from experiences of other writers. Their rituals, their tools to spark creativity or the way they do research, these skills can be shared with any good techwriter.

TAKE AWAYS: Collaborate, understand others (lunch together, beer together) -> it is not one person job, but collaborative effort. Do stuff you love to improve stuff that is hard.

Kat King: Building Empathy-Driven Developer Documentation

Who is the reader? How to analyse if the docs are succesfull? -> Did this content server your needs? (if no, would you mind reaching us?) Brown: Empathy is connecting with emotions, not with experience. People want accurate code, people can be higly task oriented -> gather feedback to understand because its not about US. Focus on devs, rest will follow.

TAKE AWAYS: Build and measure how the docs perform, because the important part is to understand the developer. (slack notification :D), Accurate code samples are the most important (issue of maintanence), classifications are not the crucial and docs needs to be easy for information foraging (SEO). And make it simple to navigate in.

Jodie Putrino: Treating Documentation like Code: a Practical Account

How to create docs with code? -> choose the right Tools (Sphinx?), automate what you can, collaborate, AGILE (define, then design and adapt).Write -> review (push request) -> test (Some sort of tools, toolset, checks) -> publish (rst for writing)

TAKE AWAYS: Nobody cares if you use automatizations or not, they care how to solve their issue. Create the best possible experience for the readers.

Jen Lambourne: Research Like You're Wrong

You are not the user, you personally know more than the user about product, research what users need (their motivation, needs and language). User research is team sport (don't do it yourself), it can be done anytime (start is good but other time is also good), find out what do you know (so you can find the news things), User Research Kanban, Question everything and try to prove me wrong, small people (5-7) is enough, but keep the rules of scientific sample. (What do they expect? Mights and more), Hawtorne effect (if under scope, you moderate your results), beware of leading questions, subjective interpretations, wants != needs (as a person I need something so that something) (Explain data source, label interpretations, answer hypothesis, make it understandable)

TAKE AWAYS: Critiques are not personal :D but take research like an academical research, talk less, think more and gather data from all people, analysis take time, wants are not needs. (@jenny_anne)

a hello from my server

ridlees / Techwriting_journal