Repository navigation
Move the blog into site/docs/blog for MkDocs Material's blog plugin - #1
Merged
Merged
Conversation
97 posts from markbac/blog-tech: 79 from blog/ and the 18-part Docs as Code series from DaC/. Each post has date, authors, categories and slug front matter and an excerpt marker. Images are copied into posts/images with credits where the source is known. .authors.yml describes Mark, and index.md is the blog's landing text. Edits are light: British spelling, headings without bold, emoji or a closing colon, emoji pseudo-lists made into Markdown lists, long sentences split, broken code fences repaired, and the Docs as Code "next" pointers linked to the real next part. Drafts are left out. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Moves the blog from
markbac/blog-techintosite/docs/blog/for MkDocs Material's blog plugin. This PR changes onlysite/docs/blog/.What's here
site/docs/blog/posts/: 79 fromblog/and the 18-part Docs as Code series fromDaC/. Each post hasdate,authors: [markbac],categoriesand a shortslug, plus a<!-- more -->marker after its first paragraph so the index shows excerpts..authors.ymlfor Mark (name, description, GitHub avatar and link). It sits at the plugin's defaultauthors_file({blog}/.authors.yml), so no setting is needed.index.md: the blog's landing text.posts/images/, with descriptive names. 23 were GitHub attachments; the 24th is the public-domain Markdown mark, used by the Markdown guide.Checks
py-doc lint site/docs/blog --strictexits 0 with Vale 3 and en-GB spelling: 0 warnings or errors. 1,954 info notes remain, mostlyHeadingCase(Mark writes headings in title case),PassiveVoice,AcronymsandWeaselWords. Clearing them would mean rewriting most posts, which is more than a light edit.--strictdoesn't fail on info.py-doc site buildbuilds both sites with no MkDocs warnings. On each site,site/buildandsite/build-tarfboth have 97 posts, the 2025 archive, 12 category pages, 9 index pages and all 24 images. I also checked that every local<img>in the built blog points at a file that exists, and looked at the index, a post with images, a category page and the archive in a browser.Dates, categories and order
git log --follow --diff-filter=Aforblog/, because the posts have no dates of their own. Posts added on the same day get one minute per file number (09:00, 09:01, …), so the archive keeps the source's numbering order.Edits to Mark's text (light)
<!-- vale PyDoc.Spelling = NO/YES -->comments.**bold**, emoji and a closing:or!removed. The words are unchanged.mkdocs-plugins,markdown-guideandbeyond-markdown. Markdown examples that contain fences now use four backticks. Before this, the example links inbeyond-markdownwere rendered as real, broken links.[OpenADR Alliance(https://…)in the OpenADR post.TODO: document later, which is an example of a docs smell, is now code, so it isn't flagged as a placeholder.Other people's content
Left out (not published)
blog/000--Welcome.mdindex.mdreplaces itblog/wip/(0-blogs-list.md,Architecture_Flashcards.md,Embedded Architecture Process Mindmap.md)DaC/SDS-wip.mdDaC/docs_as_code.mdwip/(31 networking and home-lab drafts)tech_blog/(4 home-lab posts: Nginx reverse proxy, self-hosted smart home, Raspberry Pi monitoring, expanding the NAS)Guide.md,Notes.md,blog_ideas.mdREADME.md,LICENSE,mkdocs.yml,.gitgnore,assets/cover.png,assets/favicon.pngNeeded outside
site/docs/blog/(not done here)site/mkdocs.ymladds the custom fence:pymdownx.superfencesentry. Material renders Mermaid itself, so no extra script is needed. The PlantUML blocks are all examples inside code, so they need nothing.post_date_format: longfollows the theme language (en). For British dates, trytheme.language: en-GBif Material supports it, or a custom format.categories_allowedin the blog plugin settings would catch a mistyped category in future posts. The 12 used here are: Architecture, Architecture as Code, Book reviews, Computing history, Docs as Code, Documentation, Embedded, Engineering practice, Git, Networking, Standards, Team.blog-techwasn't published anywhere (itssite/was ignored), so there are no old addresses to redirect. Addredirect_mapsif it was published.Open questions for Mark
tech_blog/: publish the four home-lab posts? They show your local domain, internal IP addresses and the network layout. If you want them, they could go in a "Homelab" category with the details generalised.mkdocs.ymlsays © 2021. Were any posts first published earlier, for example on LinkedIn? If so, real dates would be better.Guide.mdsays public posts shouldn't name past employers. I didn't check for this, because I don't know which employers to look for. Please skim with that in mind.Provenance
markbac/blog-techsite/docs/blog/posts/blog/001--Architecture-5-The_Evolution_of_Software_Architecture.md2025-02-17-evolution-of-software-architecture.mdblog/002--Why_Companies_Keep_Failing_at_Software.md2025-02-17-why-companies-keep-failing-at-software.mdblog/003--Team-1-The_Role_of_a_Technical_Leader.md2025-02-18-role-of-a-technical-leader.mdblog/004--AAC-2-The_C4_Model_Visualising_Software_Architecture_for_Clarity_and_Simplicity.md2025-02-18-c4-model.mdblog/005--Team-4-Scaling_Leadership.md2025-02-18-scaling-leadership.mdblog/006--Architecture-7-What_is_an_Architecture_Vision_and_Why_Does_It_Matter.md2025-02-18-architecture-vision.mdblog/007--Team-2-Building_a_High-Performing_Engineering_Team.md2025-02-18-high-performing-engineering-team.mdblog/008--AAC-1-Building_Better_Systems_Through_Code-Driven_Architecture.md2025-02-18-architecture-as-code.mdblog/009--Slack-Why_Overworked_Teams_Are_Less_Productive.md2025-02-18-slack.mdblog/010--Architecture-6-A_Pragmatic_Architecture_Process.md2025-02-18-pragmatic-architecture-process.mdblog/011--Why_Start_with_Why_is_Just_Common_Sense.md2025-02-18-start-with-why.mdblog/012--AAC-3-Structurizr-Bringing_the_C4_Model_to_Life_in_Code.md2025-02-18-structurizr.mdblog/013--Team-3-Navigating_Organizational_Complexity.md2025-02-18-navigating-organisational-complexity.mdblog/014--Why_Does_Software_Cost_So_Much_And_Why_Its_Not_Just_About_Code.md2025-03-04-why-does-software-cost-so-much.mdblog/015--Architecture-2-Clever_Architecture_is_Not_Good_Architecture.md2025-02-17-clever-architecture.mdblog/016a--AAC-1a-Bridging_the_Gap_Between_Design_and_Development.md2025-02-18-bridging-design-and-development.mdblog/016b--Why_Your_Software_Documentation_Shouldnt_Live_in_Work_Tracking_Tools.md2025-03-04-docs-out-of-work-tracking-tools.mdblog/017--Managing_Humans-The_No-Nonsense_Guide_to_Engineering_Leadership.md2025-02-18-managing-humans.mdblog/018--The_Mythical_Man-Month-Why_Throwing_More_People_at_a_Late_Project_Makes_It_Later.md2025-02-18-mythical-man-month.mdblog/019--Architecture-4-The_Importance_of_Architectural_Principles.md2025-02-17-architectural-principles.mdblog/020--Fixing_MISRA_C_Errors.md2025-03-04-fixing-misra-c-errors.mdblog/021--Happy_to_Work-Here_Creating_a_Workplace_People_Actually_Enjoy.md2025-02-18-happy-to-work-here.mdblog/022--AAC-4-Architecture_Anti-PatternsCommon_Pitfalls_in_C4_and_Structurizr.md2025-02-18-c4-structurizr-anti-patterns.mdblog/023--Why_Some_Companies_Struggle_with_Software_Development.md2025-02-18-why-some-companies-struggle.mdblog/024--The_Infinite_Game-Why_Playing_to_Win_is_a_Losing_Strategy.md2025-02-18-infinite-game.mdblog/025--Good_Code_Documents_Itself_No_it_Really_Doesnt.md2025-03-04-good-code-documents-itself.mdblog/026--How_to_Write_Maintainable_Embedded_Code.md2025-03-04-maintainable-embedded-code.mdblog/027--Architecture-1-Architectural_Governance.md2025-02-17-architectural-governance.mdblog/028--Why_Companies_Will_Never_Learn.md2025-02-17-why-companies-will-never-learn.mdblog/029--Waltzing_with_Bears-Embracing_Risk_Instead_of_Ignoring_It.md2025-02-18-waltzing-with-bears.mdblog/030--What_You_Should_Document_and_Why.md2025-03-04-what-to-document.mdblog/031--The_Practical_Wisdom_of_Leaders_Eat_Last.md2025-02-18-leaders-eat-last.mdblog/033--Architecture-3-Communicating_as_an_Architect.md2025-02-17-communicating-as-an-architect.mdblog/034--Peopleware-Why_Tech_Success_is_More_About_People_Than_Code.md2025-02-18-peopleware.mdblog/035--Dan_Pinks_Drive-Why_Motivation_is_About_More_Than_Just_Money.md2025-02-18-drive.mdblog/036--Start_with_Why_Leaders_Eat_Last_and_The_Infinite_Game-A_Practical_Perspective.md2025-02-18-why-leaders-infinite-game.mdblog/037-Team_Geek-How_to_Build_a_High-Performing_Engineering_Team.md2025-02-18-team-geek.mdblog/038--Adrenaline_Junkies_and_Template_Zombies.md2025-02-18-adrenaline-junkies-template-zombies.mdblog/039--The_First_90_Days-A_Practical_Guide_to_Hitting_the_Ground_Running.md2025-02-18-first-90-days.mdblog/040--Autonomy_Mastery_and_Purpose_in_Software_Engineering_and_Architecture.md2025-03-04-autonomy-mastery-purpose.mdblog/041--Maximizing_Software_ROI-Lessons_from_Return_on_Software.md2025-03-04-return-on-software.mdblog/042--Writing_Better_Software-Lessons_from_Code_Complete.md2025-03-04-code-complete.mdblog/043--The_Cone_of_Uncertainty-Why_Your_Estimates_Are_Always_Wrong.md2025-03-04-cone-of-uncertainty.mdblog/044--Reviewing_Software_Engineering_(8th_Edition).md2025-03-04-sommerville-software-engineering.mdblog/045--Making_Sense_of_Documentation-A_Pragmatic_Look_at_the_Diátaxis_Framework.md2025-03-05-diataxis.mdblog/046--AsyncAPI-Bringing_Order_to_Event-Driven_Chaos.md2025-03-05-asyncapi.mdblog/047--OpenADR-Enabling_Scalable_Automated_Demand_Response.md2025-03-05-openadr.mdblog/048--Using_RFCs_to_Improve_Software_Design_and_Architecture.md2025-03-05-rfcs-for-design.mdblog/049--arc42-A_Pragmatic_Approach_to_Software_Architecture_Documentation.md2025-03-05-arc42.mdblog/050--Building_an_Effective_Architecture_Guild.md2025-03-05-architecture-guild.mdblog/051--Leveraging_a_Technology_Radar_for_Strategic_Decision-Making_in_Business.md2025-03-05-technology-radar.mdblog/052--Supercharging_Documentation_with_MkDocs.md2025-03-05-mkdocs-plugins.mdblog/053--The_Origins_of_Unix.md2025-03-07-origins-of-unix.mdblog/054--C_The_Language_That_Built_the_Modern_World.md2025-03-07-c-language.mdblog/055--Beyond_Unix_and_C.md2025-03-07-kernighan-ritchie-thompson.mdblog/056--The_Unsung_Heros_of_Bell_Labs.md2025-03-07-bell-labs.mdblog/057--The_Origins_of_TCP-IP.md2025-03-07-origins-of-tcp-ip.mdblog/058--A_Deep_Dive_into_TCP.md2025-03-07-tcp-deep-dive.mdblog/059--A_Deep_Dive_into_IP.md2025-03-05-ip-deep-dive.mdblog/060--Git-A_Deep_Dive.md2025-03-07-git-under-the-hood.mdblog/061--A_Pragmantic_Approach_to_Semantic_Versioning.md2025-03-07-semantic-versioning.mdblog/062--Feature_Flags.md2025-03-07-feature-flags.mdblog/063--Mastering_Git.md2025-03-07-mastering-git.mdblog/064--Git_Fundamentals.md2025-03-07-git-fundamentals.mdblog/065--Git_Understanding_Branching_and_Merging.md2025-03-07-git-branching-and-merging.mdblog/066--Git_Rebasing_vs_Merging.md2025-03-07-git-rebasing-vs-merging.mdblog/067--Git_Fixing_Mistakes.md2025-03-07-git-fixing-mistakes.mdblog/068--Git_Remote_Repositories.md2025-03-07-git-remote-repositories.mdblog/069--Git_Best_Practices.md2025-03-07-git-best-practices.mdblog/070--Git_Hooks_and_Automation.md2025-03-07-git-hooks.mdblog/071--Git_Advanced_Git.md2025-03-07-advanced-git.mdblog/072--Git_Debugging_Resolving_Issues.md2025-03-07-git-debugging.mdblog/073--Git_CICD.md2025-03-07-git-ci-cd.mdblog/074--Building_a_High_Impact_Software_guild.md2025-03-07-software-guild.mdblog/075--Markdown.md2025-03-07-markdown-guide.mdblog/076--Why_Standardising_Tools_and_Processes_Across_Software_Teams_is_a_Bad_Idea.md2025-03-07-standardising-tools.mdblog/077-Git_10_Git_Trick_you_Wish_you_Knew_Earlier.md2025-03-10-git-tricks.mdblog/078--How_Long_ShouldI_It_Take_for_a_Developer_to_Be_Productive.md2025-03-11-developer-onboarding-time.mdblog/079--The_Impact_of_Interruptions.md2025-03-11-impact-of-interruptions.mdDaC/01-docs-as-code-what-it-is.md2025-05-12-docs-as-code.mdDaC/02-scoping-docs-systems-products-projects.md2025-05-13-scoping-docs.mdDaC/03-structuring-docs-complex-systems.md2025-05-13-structuring-docs.mdDaC/04-key-artefacts-across-the-stack.md2025-05-15-key-artefacts.mdDaC/05-frameworks-that-bring-order-to-documentation.md2025-05-15-documentation-frameworks.mdDaC/06-canvas-tools-for-strategy-communication-clarity.md2025-05-15-canvas-tools.mdDaC/07-architecture-evaluation-and-tradeoffs.md2025-05-15-architecture-evaluation.mdDaC/08-tools-of-the-trade-docs-as-code.md2025-05-15-docs-as-code-tools.mdDaC/09-making-docs-part-of-your-agile-workflow.md2025-05-15-docs-in-agile.mdDaC/10-living-architecture-documentation.md2025-05-15-living-architecture.mdDaC/11-beyond-markdown-rich-interactive-docs.md2025-05-15-beyond-markdown.mdDaC/12-docs-as-code-smells-and-antipatterns.md2025-05-15-docs-as-code-smells.mdDaC/13-case-study-multi-layer-docs-as-code.md2025-05-15-docs-as-code-case-study.mdDaC/14-building-a-documentation-culture.md2025-05-15-documentation-culture.mdDaC/15-templates-starter-kits-playbooks.md2025-05-15-templates-and-playbooks.mdDaC/16-deep-dive-into-adrs.md2025-05-15-adr-deep-dive.mdDaC/17-deep-dive-into-rfcs.md2025-05-15-rfc-deep-dive.mdDaC/18-software-design-specification-dac.md2025-05-15-sds-docs-as-code.md🤖 Generated with Claude Code