Documentation

[fralau]

As a few others here, I believe, I am a fan of documentation 🙂

I would like to echo @squidfunk's remark:

IMHO one of the most important goals is to show that MkDocs is an ecosystem of projects. This is what makes it so powerful. This would entail a rewrite of the documentation to better showcase what can be done with MkDocs, and how the many available plugins and extensions can work together!

I have had an idea for some time to write a general doc about MkDocs, that would present the ecosystem. Doing this in the context of an official project appeals to me.

I suggest we use MkDocs for that, with Material and a couple of carefully selected extensions. What do you think? 😛

[timvink]

I think it's relatively easy to add more documents, and hard to remove things. Like squidfunk mentioned, I think it will mean a rewrite of the docs considering the 'user journey' of a new user.

The elephant in the room is what to do with mkdocs material. See for example #2700 (comment) .

If we decide on mkdocs-material as the default theme (which I am in favor of), then we also need to carefully craft the mkdocs.org documentation so it's inline with mkdocs-material and the flow is easy for new users. Frankly, I think currently many users just begin with https://squidfunk.github.io/mkdocs-material/ and mkdocs.org is read by plugin developers, but maybe it's just me :)

[squidfunk]

If a decision to use Material for MkDocs is reached, I'm happy to help out on a migration. The immediate upside is that all frontend-related problems would be directly outsourced to me and my team, so there's more time to spend here on the flesh and bones as the skin is taken care off.

[byrnereese]

I will be honest: I am really conflicted about this. On one hand, I see Material. Oh. My. God. Really @squidfunk - what a great product. Adopting Material would catapult the project forward. I also vigorously support the idea of stoking an economy around the product. If you want this project to have a big impact, we need it to scale. And scale can really only be achieved if you have an economy driving it. So anything we can do to drive value to those heavily invested in helping to drive this project forward the better.

However, if we adopt Material, we may lose an opportunity to expand upon the use cases mkdocs is well suited for. If Material is optimized for developer websites and documentation, what would a theme look like if it was optimized for building product or more traditional websites? In other words, we could take an approach whereby we first design the mkdocs website of our dreams. Then we set to building the features that make the process of building a website like that a total breeze. We do for traditional websites what Material did for developer-/documentation-centric websites.

Amazing and impactful websites -- designed and written in beautiful Markdown. Powered by mkdocs.

[squidfunk]

I'm totally indifferent whether MkDocs uses Material for MkDocs for its own documentation or not – my comment was just meant as a general note that the project might be able to move faster, nothing more. If that's not what is decided on, no bad feelings. Really! However, as mentioned in https://github.com/mkdocs/mkdocs-team-space/discussions/4#discussioncomment-9052397, I will not be able to help out on designing and creating a new theme, which I hope you understand. But I'll be happy to hop on a call to consult, when necessary!

[fralau]

It will be interesting to define what we consider as canon, but still allowing people to chose what is best for them. I believe it is important to give not only a default path, but also avenues for discovery.

I definitely use Material, but believe that the default theme should remain the starting point; not only to honor tradition, but also to give new users a "feeling" and appreciation of what a theme is, when they discover Material.

[squidfunk]

There's also a discussion on a new default theme in https://github.com/mkdocs/mkdocs-team-space/discussions/4

[fralau]

Leaving aside the question of the theme (see also #3661 for MkDocs own doc's theme), I go back to what the documentation should contain.

I believe there is an essential work to do, to codify the subject of MkDocs in the sense of to organize or arrange systematically, especially in writing (American Heritage).

To me, there are always two types of documentation:

• educational (as in "tutorial", "first steps").
• reference

Educational documentation should be simple, accessible, but at the same time it should present the top key ideas, from which all others derive (hence, an analytical approach).

And I believe there is an elephant in the room, that we all know is there, but sort of implicit. It is plain for those with some experience of MkDocs, but unfamiliar for those who approach it for the first time. For me, it is still a half-charted continent: the modular architecture of MkDocs.

I know it is built around:

• a core (Python)
• themes (a mix of Python, CSS, HTML, Jinja2 and Javascript)
• plugins

But in my humble opinion, it is much more than just a "system". There is a masterplan, a blueprint (philosophy) behind it, which was (from what I understand) @tomchristie's original vision. It is a simple idea at the top, but it gets complicated in its ramifications. Most importantly, it is a workable idea.

Tom might tell us whether this idea was sitting there in his mind with utmost clarity right from the start, or whether it emerged little by little as he went. Nevertheless, explicit or implicit, there is a big idea, that keeps the whole project together. It is a demonstrable fact, since MkDocs is used in many projects, and we use a specific set of concepts every day when using the MkDocs ecosystem or contributing to it.

Since I had to discover that ecosystem for myself, and I know the questions and obstacles I found on my way, I might put that discovery experience to use, to forward that knowledge to others? If the idea suits you, I would like to attempt to document the "big idea" behind MkDocs and its applications.

The purpose would be to make that idea immediately accessible to others, so that they understand how it applies or start "thinking with" MkDocs to make it do what it should do (as well as other things that we might never have thought about); and for contributors, so that they find their way around the code, quickly and with certainty.

Part of that endeavor would be to write a glossary. Giving good reference definitions (applicable to our project) could be helpful to flesh out those concepts for ourselves, and see how they apply in daily practice.

But to do that faithfully, I would like to have some input and feedback from Tom. Is that something that this community would be interested in? And would Tom be interested in sharing those ideas?

[tomchristie]

Thank you Laurent, that's a very generous interpretation. I'm not sure there's any particularly novel ideas behind MkDocs, other than the KISS principle.

The URL re-writing so that you can work with interlinked markdown files, and end up with interlinked HTML and clean URLs is nicely done. And it does an okay job of using plugins and templating to provide an extensible ecosystem.

I do think there could be a more elegant version in there, waiting to get out. It's ~10 years since MkDocs started... would hope to have learnt a little along the way.

Thanking you for the enthusiasm.

[fralau]

It's my turn to thank you, for considering my idea of documentation.

If KISS was the principle, then that would be the novelty, in creating MkDocs! Documentation tools is an area where complication has been rampant.

More specifically, knowing that URL rewriting (which is, oddly enough, one the aspects I haven't fully grasped) is a key feature, and that the extensibility through plugins and templating, sheds interesting light on the project.

Actually, the most appropriate term to define that quality that several of us remarked on about MkDocs, could be elegance :

Satisfying or admirable neatness, ingenious simplicity, or precision of something. (Encarta Dictionary)

Hence my enthusiasm is backed up by my reasoning 🙂 .

Furthermore, I am easily convinced that there could be an even more elegant version of MkDocs in there, especially if that statement comes from your hindsight of 10 years since MkDocs started.

This gave me a new idea 💡 : when I started this discussion, my focus was on the past : writing a documentation that would start from the general, big simple, ideas, and then descend gently into the complications of implementation. I do believe that it would be a worthwhile endeavor.

I perceive now a second application, for the future: this elegance which you evoked, should be one of the through lines of this team's work on MkDocs. When a group forms around a software project, the individual contributions boost the project by cleaning up bugs, solving design issues and adding new features. But all these individuals also have their own ideas, needs and preferences. That introduces complication (divergence from the initial simplicity) into the design. The worst-case scenario being the "committee-driven project", where feature-creeping has turned the thing into a formless and insipid mish-mash, with a daunting 600 pages reference manual formally ratified in a plenary assembly at the nth International Congress. 😄. In any case, that divergence is necessary and inevitable, because our original designs are imperfect, and real life is... messy.

Nevertheless, there needs to remain a red thread; and experience has shown that this thread is best found in the mind of an individual (not a committee). That's why I believe that, in the interest of the MkDocs project, we should pay attention to three things:

1. Your original idea (goal, ideal, etc.).
2. What you have learnt from this 10 years experience
3. What vision you would have for the future.

Of course, all that could be interwoven in dialogue between individuals and mutual enrichment of ideas, but I believe this project would greatly benefit by pursuing your vision of a more elegant version in there, waiting to get out.