Be with people caring for documentation: a delight! #writeTheDocs #conference

Docs as code: More like docs IN code. Learning about swagger.annotations while advocating for upgrade to support OpenAPI v3. It's been a while since I worked in Java. Weird to get nostalgia vibes on a current project. Also I feel like the teacher learning the subject the night before the class. Damn I love this job. #techWriterLife #technicalWriting #writeTheDocs #docsAsCode

Another image I made and saved in my "to use in MR reviews" folder. :blobfoxdealwithitfingerguns:

#docs #WriteTheDocs #GitLab #ProgrammerHumor

@apfelkraut @darktable RTFM reminds me of Erin Grace, a force for good in the docs/user-ed space and her helpful, empathetic, practical reimagining/redefinition of "RTFM": https://www.readthefriendlymanual.com/blog #techWriterLife #technicalWriting #writeTheDocs

Silver lining on a stupid cloud: I posted recently about my bad call when structuring doc sets. The good news: my years of work to maintain consistency across projects is really paying off as I chop & hack & reshuffle & extend (variable names, conditional tags, file organization, etc.) #techWriterLife #technicalWriting #writeTheDocs

Humbling: making a well considered, strategic decision about the fundamental structure of several related doc sets that turns out just plain wrong. Not fatal, but deeply annoying. Not going to automate my way out of this one. Luckily, recent experience has already charted a new course. Oof. #techWriterLife #technicalWriting #writeTheDocs

@Tarah is the team 'git-markdown' savvy or is it better to have a WYSIWYG of some sort?
Don't hesitate to add some hashtags like #writethedocs (a community of tech writers who may have answers)

"Documentation is like sunshine"

What does that even mean?!

Join the https://dora.community tomorrow at 7PM UTC as we shine a light on how internal documentation drives technology performance.

Join the https://dora.community Google Group for meeting details and a calendar invite.

#DevOps #WriteTheDocs #documentation #research

I've spent on and off over the last year writing a new library, and because I was actively discovering the design, I didn't try to write docs that would keep changing. Finally spent the last three days writing docstrings, and then I need to write full pages as well. It feels more exhausting than all the coding right now, but it will be worth it! #WriteTheDocs

#Documentation #WriteTheDocs #2023-07 #YAML #PlantUML

- https://www.writethedocs.org/blog/newsletter-july-2023/#documenting-yaml-files

- https://plantuml.com/yaml

To document YAML files, look at current reference documentation formats and tools. For example, JSON Schema (https://json-schema.org/) and jsonschema2md (https://github.com/adobe/jsonschema2md) are two viable options for describing schemas and configuration files.

OpenAPI documentation in YAML or JSON can also serve as an example of YAML configuration documentation. Consider OpenAPI (https://swagger.io/specification/) as a resource to explore.

Many documentarians create example YAML configuration files using comments, placeholders, and links. They also use tables for lengthy references and some use PlantUML for YAML visualization (https://plantuml.com/yaml) .

Writers also emphasized the significance of YAML schemas and the possibility of automated documentation creation. Some suggested using JSON Schema to design schemas, produce Markdown documentation, and use the JSON Schema Store (https://www.schemastore.org/json/) to validate files such as for GitHub and Kubernetes configuration.

#Documentation #WriteTheDocs #ReadTheDocs #Python #Django #Sphinx #furo

#Awesome project of the month (2023-07)

- https://blog.readthedocs.com/newsletter-july-2023/

- https://docs.django-cms.org/en/latest/

We are adding new entries to the list of Awesome Read the Docs Projects 🕶️ (https://github.com/readthedocs-examples/awesome-read-the-docs).

- https://github.com/readthedocs-examples/awesome-read-the-docs/commits.atom

Feel free to open an issue or pull request if you’ve seen something that might inspire others.

This month’s addition is the developer documentation for django-cms (https://docs.django-cms.org/en/latest/), which is noted for being both extremely extensive and well-organized at the same time.

It uses the Furo (https://pradyunsg.me/furo/quickstart/) theme that has full integration with Read the Docs’ reader extensions.

Another way documentation provides value: stick around long enough and your docs will be used for trademark renewal. #technicalWriting #techWriterLife #writeTheDocs

Overheard a gaggle of execs baffled by MS Word behavior. Couldn't keep myself from wandering over to contribute. Learnings and fixes effected. They also had the correction reaction: "That makes no sense!" #MSWord #techWriterLife #technicalWriting #writeTheDocs

A short post from me about a comprehensive list of tools and other info for tech writers, from indoition: https://ffeathers.wordpress.com/2023/06/04/comprehensive-list-of-tools-and-other-info-for-tech-writers/ #WriteTheDocs #TechComm #TechnicalWriting

Just in case anyone thinks my work is all sunshine & rainbows: Name change of a fundamental service. Oof. I tried my best to decouple my doc process from this freaking thing, keeping variables & structure product-name-agnostic while retaining semantic meaning for usability. Probably could limp along, but if I don't fix this now, I know the name change will bite me in the future and annoy me constantly. #techWriterLife #technicalWriting #writeTheDocs

30 minutes in a room reviewing doc with 2 extremely helpful senior devs. My buffers are overflowing. Such a good place to be. I have a lot of work to do. #techWriterLife #technicalWriting #writeTheDocs

I've inherited an internal website project with unrealistic expectations, poorly defined goals, & actively shrinking resources. The website has quite a few empty pages. Shocking, I know. I hate "under construction" pages. This is my "under construction" page. IDGAF in the most constructive, helpful way I can. #techWriterLife #technicalWriting #writeTheDocs

At a previous job, I set up #Vale to lint our tech docs (in a docs as code publishing flow) and I loved the power that the natural language processing (NLP) and customized styles gave me to standardize the docs and check for mistakes.

When I started playing with LLM chatbots, I immediately thought they could be a more convenient application of that. But so far, nope.

#nlp #llm #GenAI #WriteTheDocs

@djwfyi how wonderful! I’m a big fan of #WriteTheDocs!

👋🏻 obligatory "i'll be at #WriteTheDocs next week" post, in case anybody in this federated tootiverse wants to connect.