501–510 of 524 posts
Earlier quoted context omitted.
Diataxis seems to be a fork of Divio. But according to the network graph on GitHub, Diataxis seems to be more active, although both of them still receive updates.
From the GitHub page, it looks like Divio is actually a fork of Diátaxis. divio/diataxis-documentation-framework is forked from evildmp/diataxis-documentation-framework, and evildmp is Daniele Procida, the creator of the latter repository and the maintainer of diataxis.fr.
I'm convinced that documentation, even for large companies, should just be an Obsidian vault of markdown files maintained via git which is just rendered on the web either using a simple static site generator or using Obsidian Publish. When I brought this up at my last company it got dismissed as being 'too technical'. I know git can be tricky but it cannot be that difficult to teach people from non technical departme…
Earlier quoted context omitted.
Usually a tech writer is also some sort of PM role that gets to chase developers and get them to explain what's in their head. Sometimes you have to have such a person on board.
I once did an internship that involved chasing down senior devs and generating documentation for them (needed for FIPS certification). It was a great way to learn about the tech stack. Suffice it to say I didn't have any PM role at all.
Earlier quoted context omitted.
I do get what you're saying because I struggled with it for ages. There are good GUI tools like Sublime Merge for easy conflict resolution now which would be one solution. I do think a web interface that just automatically commits by just adding your text in addition to the new text along with a warning would probably be the easiest solution and then just have someone edit it after the fact. It's not been my experien…
I think even the idea of merging changes is a step too far for all but the most technical users. Most user's idea of what it should look like start and end at a word-like UI, so having to introduce the idea of merging different copies together and resolving conflicts is too far outside that view. In my opinion this is why Google docs has become popular because it solves that tricky problem of having to think about ho…
As much as I hate to admit it, sharepoint works better here.
On the upside for Google docs, commenting and edit suggestions work so well it’s become easier convince people to use Google docs without downloading copies.
Earlier quoted context omitted.
> Primarily because it's a far, far more complicated job than that and you can't really hire someone off the street to do it effectively. This comment is absolutely true and many, of not most, companies fail to understand it. I think the problem stems from corporate-people thinking, "Why should I pay a writer when we all speak English (or whatever language) and can write it ourselves." And that's why so many companie…
> I was a software engineer for 30+ years and got completely burned out on it, so I left engineering to do technical writing How did you make this transition? Any credentials/certifications you needed? Did you transition within the same company?
My current employer was sold to me as a "high documentation" place. What it means in practice is that if you're trying to do something there are 5 outdated documents describing the decision making process for how the project was run, and no documents about how to actually use the resulting software. Occasionally if you ask how to actually do a task in Slack someone will yell at you that you should have searched for a…
I would suggest introducing two things. First, introduce The Diataxis framework ( https://diataxis.fr/ ) for documentation. It makes people think about documentation in a more structured way, and allows you to be more specific in the types of missing documentation. (High documentation cultures are often good with explanation but not tutorials, for example.) Second, I would introduct the idea of a Documentation Portfo…
Earlier quoted context omitted.
Does a README in every folder in a Github repo meet the requirements? What is the lowest friction way to do this?
Probably not IMO, it's very unlikely your source tree is structured the same way good docs should be. Docs are often task oriented, code is usually component oriented.
Is there any way to achieve this within Microsoft's suite? Sadly we adopted Microsoft O365, SharePoint, Teams. How can you organize the org effectively is beyond me, how does MS do it? Are they actually using their own tools they sell others? In our org, some departments/teams/sites have just a SP, Others have a teamspace with separate SP/document store. Worse, any meaningful file structure/hierarchy you come up with…
Ex-Microsoft, current GitLab employee here. The way you describe using Microsoft's tools in your company is pretty much how things worked at Microsoft while I was there 3 years ago. If you'd like to build a handbook similar to GitLab's, this page of our handbook can be a great starting point: https://about.gitlab.com/company/culture/all-remote/handbook...
That is mind boggling. How on earth can MS have an efficient knowledge management with this setup?
How frustrating was it too use for you?
The most sensible way forward seems to me would be just set up a single company SharePoint with a doc store with a predefined data layout. No associated team space around that. Move communication 100% to slack. Link / pin the relevant SP folders to the slack channels.
Just for the dev team this would work as we never moved chat from slack to teams. But we need to
1. interact with the less technical parts of our org (product management, quality & regulatory, BI, V&V, Legal etc)
2. Interact with colleagues from other subsidiaries.
They all use teams, so conversations & especially meetings will happen on teams, people will still store docs and notes there just out of convenience or lazyness.
I do not know how to solve that conundrum.
My current employer was sold to me as a "high documentation" place. What it means in practice is that if you're trying to do something there are 5 outdated documents describing the decision making process for how the project was run, and no documents about how to actually use the resulting software. Occasionally if you ask how to actually do a task in Slack someone will yell at you that you should have searched for a…