Introduction
In the software development ecosystem, there is often friction between software developers and technical writers when it co...
For further actions, you may consider blocking this person and/or reporting abuse
As for tools integration, is just a matter of finding one. I saw that problem when I started to work on my personal blog and decided to create a "bridge" for people who are a bit less tech savvy that connects MkDocs with Obsidian.md (both are using Markdown files). This way you can have a great editor that helps a lot with text formatting and cross documents linking and probably one of the best building and presentation side (especially with Material for MkDocs). If you are interested in my project take a look at MkDocs Publisher.
Will definitely check out MkDocs Publisher. Thank you.
Also diagrams as code - packagemain.tech/p/software-archit...
I agree 💯. With Docs-as-Code you are able to convert plantuml, graphviz, mermaid or drawio codes into diagrams that help you to add more details to your documentation.
Java JEP 467: Markdown Documentation Comments" uses my original method on 2019-02-17
Markdown Literate programming that don't break the syntax of any programming language
Live preview in Notepad++
I love how rust has cargo doc which supports this sort of stuff natively.
Very well complied!
Thank you 🫡
Well written post
Thank you 🫡
Very nice read 🔥
We are currently using Vue for our application and I think with this approach we could use something like VitePress to generate docs as webpages for markdown documented requirements. That way the actual functionality/code is closely coupled to the requirements documentation and testers/stakeholders can review these for testing/understanding.
However, i'm not sure about other documentation that isnt directly connected to the current version of your code. There a system that just allows for quick editing and saving could be more beneficial. What do you think?
But at the end it really depends on the team size, experiences, use cases, project management, ...
If VitePress supports versioning then it will help to have your other documentations linked to your current version so that stakeholders can choose which version of the documentation to use based on the code version.
You can also checkout MkDocs and Material for MkDocsto see if it matches your use case.
Yea, I think for our use case simply linking is more than enough. MKDocs seems nice but I think we got more flexibility with VuePress since we are using Vue already so its not something new to learn or another technical workflow to add to the stack.
But really nice post, I'll definitely come back to this in the future.