Hacker News Reader

This is the assessment I have, EVERY way to manage documents or knowledge or whatever is about as ~80% as good as the ideal solution at worst. This is a problem you can spend a lot of time bikeshedding and where it's questionable to not just use the path of least resistance tools that you already have at hand.

The #1 actual problem and differentiator all these tools has is search. The #1 thing you can do in my experience to make your documentation higher quality is to template it and make it consistent as this makes it far easier to quickly grok.

Structured documentation is such a benefit toward this, and also such a controversy within teams.

Aside from the many standards for structure and the challenges of info architecture, there are a surprising number of technical writers who are hard to convince, or cannot be convinced, to write within any sort of structure or template. Either they have to be sold on it constantly, or cut loose or moved away from product docs and toward blogs or training materials.

A writer who can not only work within a structure but also can appreciate and leverage it is incredibly valuable to a docs team, and I believe the pipeline that develops candidates for technical writing doesn't prepare folks for how much weight this carries.

> If you're using GSuite, just use their stuff.

I am building a small business with 5 employees currently. We rely on quite a bit of tech but are not a tech thing (med industry). We use Google Workspace as our internal center piece.

We have also decided to pass on Notion to stay in the suite and not complicate things for a semi-technical staff – but I can definitely feel that the lack of a solid wiki substitute in GW is an issue and does complicate things.

It's easy enough to just open a blank page in either Google Docs or Notion and start typing. The power of Notion is in the incredibly low amount of effort you have to pour into knowledge upkeep. Tying it all together. Cleaning it up. Keeping it accessible and inviting to explore and expand.

Not being able to adhoc create and link documents, not having easy templates and powerful inline tables, working with images without having to manually resize them to make sense and people starting to fuck with colours and fonts (just to name a few things) is really cumbersome and makes the task of maintenance really heavy.

Google Sites exists. It just isn't good enough (reasons outside the scope of this post). For Docs or GW in general hope is on the horizon with smart canvas, web view for Docs and more coming.

Lastly, money of this magnitude is really, really not a concern at our little shop. We generate income. Employees costs thousands of $ per month. Keeping people motivated, using the tools and making both collection, access and maintenance of knowledge simple is.

If I could pay another $10/month/user for a Google Notion I would.

Interesting. Having used various tools, I'm leaning the other way back towards Google docs for simplicity and search. The key is that search works really well along with collaboration. Linking docs in gdocs has also improved.

Yup Google doesn’t have a good alternative for a wiki and they are invaluable in companies. Notion is the best wiki I’ve seen, not trying it because it isn’t Google is bad advice

The reason we decided against it, is that tech fatigue is a super real thing and it gets sobering fest when you deal with non-technical folks who actually just want to get a completely unrelated job done.

They are just not enthusiastic about new organisational tools. They just want something simple and familiar.

We had a Notion test run. It would have taken additional energy to convince people to get accustomed and actually use it, more than we were willing to expend on this matter at the time.

Each new tool adds a burden. While the exact opposite is true for a lot of tech folks (to an unhealthy degree), just the idea of "yet another tool" is draining to a lot of normies and something I have come to strongly consider.

It doesn't matter what you use, the important thing is to foster a culture of writing stuff down and keeping it updated.

For onboarding docs the first task of the person being onboarded should be to update and improve on the onboarding documentation.

And everyone in the organisation should follow the Scout Rule of documentation, whenever you read a doc, leave it better than it was when you started reading it.

agreed, but confluence leaves much to be desired.

Is this the equivalent to the “pre-mature scaling” phenomenon in tech?

In the early days of a startup, I agree with your statement. Once the company gets significantly bigger, these things start to matter a lot.

Yes I’d like to echo this.

Our SaaS is 16 years old now. In the early days it was all about product market fit, generating cash, basic survival. We were too busy focusing on the latter to worry about things like documentation systems at scale.

But there was definitely a threshold that we crossed where we knew things would likely work out - at this point we started paying attention to systems at scale.

And boy am I glad we did that! Had we not taken that crucial step, we’d be suffering today.

Point is, one can’t afford to skip over these things in the early days. But it’s a tricky balance, because doing it too early is also counter productive.

I agree with you, but don't think the issue is one of documentation. Rather, it is an issue of communication.

To borrow a concept from Starcraft, what has worked well in my experience is for every member of a team/company to clearly understand their "macro loop". This involves being aware of the set of chat channels, email threads, code repositories, and documents that are most relevant to their work in the near term and in the medium term. Everyone on the team should be:

1. Checking these sources at a regular rate (once a day, once a week, once every two weeks).

2. Reflecting their work in these sources to the extent that it's relevant to their team mates.

Macro loops cannot be forced onto someone, but they can be reinforced by the rest of the team. For example, if you lead a weekly meeting and always have the meeting doc up on a shared screen, people will naturally start refer to it themselves when they need the context it contains. Or if a particular document is always linked in answers to a certain question, it will make its way onto indexes and bookmarks.

The particular systems you use to represent these things -- Slack vs. Discord vs. IRC vs. Google Hangouts for chat, GMail vs. custom servers for email, GitHub vs. GitLab vs. Bitbucket vs. self-hosted git for code, Docs vs. Quip vs. Dropbox Paper vs. Office 365 vs. Notion for docs -- really don't have a significant effect on how well a team runs its macro loops.

Use what you've got. My experience matches this, but with one exception: Confluence. It's where documents go to die.

Confluence, like Jira needs at least one person whose full time job is administering and organizing it it if the organisation is over a dozen people.

Otherwise it'll turn out to be like any wiki anywhere, a graveyard of documents.

Therein lies the business benefit, if you use SharePoint you need two or three people instead of one business analyst.

My company has 60 staff and SharePoint with the Teams Wiki integration is so _demonstrably_ worse.

I didn't think I would become an advocate of Atlassian and there might be some disruptors out there in that space, but of all the big providers there, Oracle, Microsoft. Atlassian are still hear and shoulders above the rest.

JIRA is slow, but I don't hate it. Once setup, there isn't much else to do. Confluence is terrible b/c the search is so bad. I hate when I know a document is in Confluence and I have to come up with some magic search query to surface it.

My last team used Google Docs exclusively, and writing a doc was where it went to die.

I absolutely adore notion, but completely agree with this assessment.

In terms of multi user usage, I use it for home projects with my partner and family, and at work I use it for specific projects across teams where the number of users is usually less than ten.

The beauty in it is being able to rapidly build up documentation in a collaborative way without having to use separate tools, a la a traditional office suite.

The idea of maintaining hundreds of documents across as many users though is absurd. Once we've gotten past the point of onboarding and scaling up our project, we transfer to slower but more reliable tools like _shudder_ Confluence, which may be a messy nightmare for individuals when compared with notion, but which has absolutely no trouble with scaling across dozens of teams.

I support this statement