log4brains
mm-docs-template
Our great sponsors
| log4brains | mm-docs-template | |
|---|---|---|
| 6 | 1 | |
| 1,057 | 7 | |
| - | - | |
| 0.0 | 7.3 | |
| 3 months ago | 6 months ago | |
| TypeScript | PowerShell | |
| Apache License 2.0 | - |
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.
log4brains
-
A practical overview on Architecture Decision Records (ADR)
There is an interesting win-win tool called log4brains, that can turn your markdown into a static website. It's also integrated into MADR template. I haven’t had time to try them yet, but it's in my backlog.
-
Can't bring myself to produce code any more, any ideas to help?
I'm a solution architect in my current job, and I love it because I still get to solve technical problems and help/mentor more junior developers but I don't really write code anymore (except on minor occasions and it's mostly by choice). The tradeoff is I have to write docs and make presentations, but I learned how to do that easily enough.
- Build some good documentation habits in your team with ADRs (Architecture Decision Records) and their go-to tool: Log4brains
- Document your project by logging your decisions chronologically with ADRs (Architecture Decision Records)
- Log4brains: Document your projects by logging your decisions chronologically with ADRs (Architecture Decision Records)
- Document your projects by logging your architecture decisions chronologically with ADRs (Architecture Decision Records)
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
What are some alternatives?
adr-tools - Command-line tools for working with Architecture Decision Records
Doxide - Modern documentation for modern C++. Configure with YAML, output Markdown, post-process with Material for MkDocs.
vscode-front-matter - Front Matter is a CMS running straight in Visual Studio Code. Can be used with static site generators like Hugo, Jekyll, Hexo, NextJs, Gatsby, and many more...
docs - The documentation for Firefly III
documentalist - :memo: A sort-of-static site generator optimized for living documentation of software projects
mm-docs - Documentation system in a docker container using mkdocs, plantuml and many more
mdSilo-app - Lightweight Knowledge Base and Feed Reader.
pydoc-markdown - Create Python API documentation in Markdown format.
prpl - Lightweight library for building fast static sites
MkDocs - Project documentation with Markdown.
slant - Beautiful static documentation for your API
Optic - OpenAPI linting, diffing and testing. Optic helps prevent breaking changes, publish accurate documentation and improve the design of your APIs.