I spent two years trying to do what Backstage does for free

And it worked, it reached front page again. I wonder how often then recycle articles and post them with fake dates.

Some datestamp next to multiple areas with a "last reviewed/approved on" info would likely be useful, esp if someone could flag items that are known out of date/wrong/broken for review, even if they didn't know what 'correct' was. I've hit this multiple times as a new person on a team/project - at least those that had moderate documentation. I know "example A" doesn't work, but I don't yet know why it's wrong or how to fix it, but flagging it for review would help me not lose track of it.

That part.

Typed, properly named code doesn't need 'docs' per se. Documented code like:

    // Sender public key 
    const spk;

    // Send tokens 
    function txV(){ .. }

    const sender: PublicKey

    function sendTokens(){ .. }

Those were being maintained in the wiki.

The basic assumption is that most developers don't hate writing documentation other than they don't feel like they do it well and don't feel like it's effective. The best way to make it feel effective is threefold - build a proper framework on which you can attach the documentation for discoverability; build an expectation for a documentation portfolio; and build it into your definition of done at the feature level;.

1. Build a proper framework. Techdocs is part of backstage and uses your own git repository to build it in markdown. https://backstage.io/docs/features/techdocs/techdocs-overvie... has more information. Diataxis is a good start to how to think about the types of documentation. https://diataxis.fr/ is what I use to separate out the types of documentation that need to be written. Most documentation in my experience is written as "explanation." Having API reference and howtos are important, and so many howtos are just built out of asking someone on slack anyway.

It is a matter of saying, "you've already done the work to discover this: just put a rough draft where I've put it to be and people can refine it as they go."

2. Build an expectation of a documentation portfolio. I write about that at https://www.ebiester.com/documentation/2020/06/02/agile-docu... but it was a concept written about in Agile Documentation. Start with "these are the minimum requirements for a new project" and keep it very light. Build documentation, codebase expectations, and a quick architectural tour is likely enough to start and the rest will follow.

3. Build it into the definition of done. This takes management buyin, but it means taking it into account for the schedule as technical debt originally. It will not slow you down in the end, but the activation energy of learning takes some time. But just like unit tests or manual testing, there's a set of expectations that are baked into calling something done.

I think a bonus is that so much of documentation is built through our chat and email programs, and just having the courage to copy it out and clean it up a little or take videos and transcripts of debugging sessions is a good start, but it's easy to make a mess. The key is categorization.