mm-docs-template
Optic

mm-docs-template | Optic | |
---|---|---|
1 | 12 | |
9 | 1,408 | |
- | 1.4% | |
6.1 | 8.1 | |
8 months ago | 7 days ago | |
PowerShell | TypeScript | |
- | MIT License |
Stars - the number of stars that a project has on GitHub. Growth - month over month growth in stars.
Activity is a relative number indicating how actively a project is being developed. Recent commits have higher weight than older ones.
For example, an activity of 9.0 indicates that a project is amongst the top 10% of the most actively developed projects that we are tracking.
mm-docs-template
-
Why Your Company's Documentation Sucks
This view is too much simplified. If docs where tree vs graph we would probably have at least some orgs doing it right, while there are literarily almost zero.
Some of the important aspects of good documentation is:
1. Narrative style. You can't do ad hoc whatever wherever and call it a day. Most people don't have it and many are quite illiterate IMO. You need to practice this and most engineers don't like that. Hell, even most seniors don't like writing tickets IME which take almost the same time as putting garbage on Slack. I created templates on both GH and GL and almost nobody uses them even tho you don't need to think about anything but follow few rules.
2. Its quite hard to know what level of detail to put in documentation. You need a lot of experience for this - put to much, and it gets quickly outdated, put too little, and it doesn't convey much. Good documentation exists on multiple levels - as bunch of markup files "on the spot", as formal hi and low level documentation and also those are usually affecting different target groups so you actually need to design docs.
3. Documentation is a service. It has source code, build procedure, automatic link checking, export to bunch of format, crosslinks, variables, macros, configuration for different environments, abbreviations, definitions. Its quite hard to get it right. After years of struggle on different projects I finally created my own stuff [1] that I use on all projects, for docs spanning 50-500 pages. I maintain that for years now, constantly (so yeah, its a job).
[1]: https://github.com/majkinetor/mm-docs-template
Optic
-
Show HN: LintGPT – Write API Style Guides in Natural Language
- Minimizing API calls. The first time you run LintGPT it is pretty slow because it has to run every rule across every part of the API specification (1000s of calls). But we shouldn’t have to repeat that work. Most of the time parameters, properties, etc don’t change and neither do the rules. We’re building caching into our web app to make this fast / save $ for end users.
Happy to answer any questions. I really think there’s a huge use case here for linting all kinds of code, config, database schemas, policies in ways that were never possible before. And personally, I like the idea of having these smart tools guiding me towards making my work better vs generating it all for me — idk something about that just feels good.
[0] https://github.com/opticdev/optic
- Show HN: Generate OpenAPI from Your Tests
-
Testing for Breaking Changes in Fastify APIs
Recently I was approached by a team that needed help testing their Fastify API for breaking changes. Fastify was making it easy to quickly ship a lot of new functionality, but breaking changes were making it through Code Reviews. They were not finding out the changes were breaking until a consumer emailed them — not good. The developer who reached out saw my work on the Optic project and asked for help.
- Get notified when the APIs you depend on change.
-
What is OpenAPI?
Optic
-
"Git for APIs"?
I'm really happy to say I've started a new job at Optic, and with this comes the learning process of getting more depth with new technology and its use cases.
-
How do you usually get API documentation for your apps?
I’ve been working on this open source project https://github.com/opticdev/optic
-
Why Your Company's Documentation Sucks
Our documentation sucks because it is time-consuming to do documentation properly.
I am hoping to fix this by introducing Optic [0] to automatically handle generating API diffs.
[0]: https://github.com/opticdev/optic
-
Paw is joining Rapid API
I've recently been using Optic (https://useoptic.com/) which does some cool things in the API tools space, there's potential there to have a CLI UI and they have the history part already but similar to what people are saying here about the web UIs, I don't like theirs much.
-
Rust made my open source project 1000x faster
I'm assuming it is the url mentioned for the language chart: https://github.com/opticdev/optic
What are some alternatives?
mm-docs - Documentation system in a docker container using mkdocs, plantuml and many more
Swagger Client - Javascript library to connect to swagger-enabled APIs via browser or nodejs
log4brains - ✍️ Architecture Decision Records (ADR) management and publication tool
FarFetch - Modern Fetch API wrapper for simplicity.
Doxide - Modern documentation for modern C++. Configure with YAML, output Markdown, post-process with Material for MkDocs.
Rails Ranger - 🤠 An opinionated AJAX client for Ruby on Rails APIs
pydoc-markdown - Create Python API documentation in Markdown format.
SapphireDb - SapphireDb Server, a self-hosted, easy to use realtime database for Asp.Net Core and EF Core
docs - The documentation for Firefly III
wretch - A tiny wrapper built around fetch with an intuitive syntax. :candy:
MkDocs - Project documentation with Markdown.
oasdiff - OpenAPI Diff and Breaking Changes
