421–430 of 524 posts
Earlier quoted context omitted.
So you are now the gatekeeper?
If an individual employee is going to put all that work in without being asked to or being given scheduled time to work on it they should get something in return.
Earlier quoted context omitted.
Confluence (and all of the similar products) can be used successfully, but you need the teams to agree on and enforce a logical document hierarchy. It’s not really difficult to organize a company wiki into teams, projects, and other logical divisions if you make it a priority. The primary failure mode I see is when people just throw random documents into Confluence wherever convenient at time of writing and never go…
Agreed, we use Confluence and use an agreed upon structure. It works fine from what I've experienced.
I personally have never seen it work, but of course I've also only seen a handful of data points.
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…
Can all your engineers see all your other engineers' code? It's hard enough to get code to do what it says it does; I've very rarely seen documentation that's correct.
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…
This approach is definitely possible with a good web-based git IDE. We use gitlab's webIDE and have taught a few very non-technical (even temporary) employees how to do simple commits of markdown files (the trick here is high visibility into their commits -slack messages- and safeguards to make sure important things don't go live via CI too soon). There's a number of rough edges to sort out but this is vastly simpler…
Earlier quoted context omitted.
I'm sure these are great technological answers but this problem can be solved simply and quickly by a human. Not every issue needs to be solved by a butter robot. Why not employ a technical writer/documenter/whatever job title you like, even as a temp, whose sole job is to sort out the mess of documentation you have and then to write new documentation as you move forward?
> Why not employ a technical writer/documenter/whatever job title you like 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. Typically in a tech company a tech writer is going to know almost as much or more (after years of experience diving into every detail) about a given technology or application or API, and so that begs the quest…
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 companies have shitty documentation.
> ...so that begs the question why not make twice as much working as a software developer and not have to sort out these types of messes?
I was a software engineer for 30+ years and got completely burned out on it, so I left engineering to do technical writing. So far, I like it much better because I have far more control over my time. In my experience so far, the sorting-out-messes work is about the same in either field. Both jobs are pretty complex. I also make exactly the same as I did while working as an engineer.
I think the secret to not being first on the chopping block is to show you're delivering value to customers and internal teams. At least I attribute that to my survival through multiple layoffs so far.
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 gets sabotaged when new channels are created as they automatically introduce new folders. You cannot bind a teams channel to a separate folder in a SharePoint. Also, We have private project teams springing up and large fragmentation of information. If you do not know that a certain project space was set up you cannot find or join it.
Going with a "single Teamspace" for the whole org doesn't work either without being able to have nested channels/groups. The org is too large and complex.
I'd love to have a gitlab style handbook to be used in our org to organize knowledge and information, but I do not know if and how it could be set up technically.
Earlier quoted context omitted.
Agreed, we use Confluence and use an agreed upon structure. It works fine from what I've experienced.
Can you share your structure? Or do you know any good open-source ones? I personally have never seen it work, but of course I've also only seen a handful of data points.
Earlier quoted context omitted.
> Why not employ a technical writer/documenter/whatever job title you like 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. Typically in a tech company a tech writer is going to know almost as much or more (after years of experience diving into every detail) about a given technology or application or API, and so that begs the quest…
You explained why no one wants to take the job in the typical company. They would be disrespected, and likely soon fired. But a different question is, why is no company trying to do this differently? Like, hiring one good tech writer to maintain the company documentation, and paying them as much as they pay the developers.
There are three things that I think are preventing technical writing from being more widely valued:
1. Software companies tend not to distinguish between technical writers who are good at English vs. technical writers who are good at engineering, understand their audience, and can articulate complex ideas to that audience effectively.
2. Technical writers who are good at English make about half as much as technical writers with engineering skills, but they also muddy the hiring waters and drag salaries down for everyone else.
3. Most corporate-people think because they can type up a decent email they can write technical documentation themselves. They're usually wrong on both counts.
Earlier quoted context omitted.
> Why not employ a technical writer/documenter/whatever job title you like 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. Typically in a tech company a tech writer is going to know almost as much or more (after years of experience diving into every detail) about a given technology or application or API, and so that begs the quest…
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.
Earlier quoted context omitted.
I'm sure these are great technological answers but this problem can be solved simply and quickly by a human. Not every issue needs to be solved by a butter robot. Why not employ a technical writer/documenter/whatever job title you like, even as a temp, whose sole job is to sort out the mess of documentation you have and then to write new documentation as you move forward?
> Why not employ a technical writer/documenter/whatever job title you like Who would supply that person with the information required to write the documentation?
In my opinion, companies should hire subject matter experts who can write rather than just someone with an English degree. I've fixed a lot of terrible documentation written by English majors with no engineering background.