Revised the content on the https://t.co/d243aQebEz landing page to focus more on the differences between Docploy and other documentation solutions. With a heavy emphasis on the testing piece.
We have been really impressed by @markdoc. We have been using it to create our callout and snippet components. You can focus on writing Markdown without worrying about any technical implementation. #markdoc
@simonbrown@Felienne That's super nifty. I could see a use case for SREs to confirm their diagrams are always up to date by doing this. When I was working at my previous company, I lost confidence in a lot of architecture diagrams because I couldn't confirm whether they were still up to date.
Continuous documentation… DocOps… These terms play on well known software engineering processes, like continuous integration and DevOps. For us, it is applying the same software processes to our documentation to make them as resilient as software. #docops#docsascode
@jaredhanson Do you want to avoid the library, or do you want to avoid having to learn the framework? If it's the latter, I am building a tool, @docploy, where you add Markdown to a docs/ folder, and it will publish a doc site for you. This way, you can focus on writing, not developing.
Whenever possible, maintain the user documention of your project right next to the code in one and the same repository. That way, docs are implicitly versioned, and it's much easier to enforce a "no feature work without doc updates" acceptance criteria for pull requests.
@gvwilson @judell I'm building a tool at @docploy that couples together your documentation's code snippets and your CI so a build will fail if your code snippets go out of date and fail. I would love any feedback on it!
@ndimares@StripeDev@docusaurus I built @docploy using Markdoc. Markdoc lets you render Markdown in React or pure HTML. A better comparison to Markdoc is MDX rather than Docusaurus. I like Markdoc because it decouples the Markdown from React and validates that your components have the right inputs.
@TechWithHannah Firestore's "Get started" page shows you the basics of how to read and write data: https://t.co/Bf5aMGoOHB
If you want to go deeper, there are pages that give more thorough explanations of reading or writing data.
@ImSh4yy I wasted a few hours following outdated wiki steps.
A month later, I saw someone else from my team run into the exact same issue when they tried to follow the wiki.
I wondered who else ran into the issue and forgot to update the wiki, too.
So, I built https://t.co/d243aQebEz
@shellscape@UriGoldshtein I recommend using your CI to validate broken links and test your code snippets. Once you can integrate these checks in your CI, your docs should not break without you knowing about it.