Handing a documentation project to another Technical Communicator: tips & tricks

The phases of project initiation and project closure are substantially covered in blog posts, talks, and other resources across the TechComm society. Today, I would like to address a less frequently discussed phase – replacing a technical communicator in a project team.

Continue reading

Advertisements

Documenting APIs: Open-Source Tools Review

Have you ever been assigned a task to write API documentation, and then you got lost in tools for creating it?

If yes, I would like to share with you amazing research by Diána Lakatos who analyzed loads of info to provide us with a magnificent overview of open-source tools for documenting APIs.

Continue reading

Documentation as a prerequisite for successful CSIS

Complex System of Information Security (CSIS) comprises a set of organizational and technical measures aimed to ensure the protection of information circulating in the system from disclosure, leakage, and unauthorized access (c).

If your company is implementing the CSIS, it’s in for reinforced credibility and boosted sales. And you as a Technical Communicator are in for a bumpy ride. 😊

Let’s take a look at a grueling journey of meticulously described processes, roadmaps, and guidelines that need to accompany every stage of the System development.

Continue reading

Myths about information development: Busted

People tend to create stereotypes about things they don’t have much insight into. I broke into information development from a different industry, and I’d like to share my own experience of mythbusting. 

Before starting my career as an Information Developer, I was a translator and had little awareness of the role and its responsibilities. As a philosopher once said, “Theory without practice is empty”, and I’m glad I got a chance to fill the void and break my stereotypes during the first month of practical experience. Let me share some of them with you. Continue reading

TechComm and Artificial Intelligence (overview of a podcast by Seth Earley)

Nowadays, artificial intelligence is a central subject in the constantly evolving world of technologies. It is believed that in the long run, it will define the next generation of software solutions. Simultaneously, there is a lot of anxiety that Artificial Intelligence (AI) is going to lead to significant labor displacement.

So, in the context of Technical Communication, does the advance of AI mean that our trade is doomed to extinction as well?

Continue reading

Leading by example in legacy projects

One of the typical ways for agreeing to have project documentation in place is this:

  1. Customer voices the need for documentation (on a side note, product-based software companies are not considered in this discussion).
  2. Documentation team provides the estimates.
  3. Estimates are adjusted and approved.

This works well for new projects and new features in existing projects. On a side note, this also assumes that the people who give the final approval for documentation do understand why documentation is needed.

But what about legacy projects, the ones that are poorly documented or not documented at all? How do you convince the company (or the customer) that documentation is needed?

Continue reading

Operation Cleanup: CSS refactoring for InfoDevs

Hey, fellow writers who work in MadCap Flare! Have you ever opened your CSS style sheet in a text editor and checked if it contains conflicting entries, style duplicates, or empty style definitions? Maybe there are unnecessary repetitions of a property assigned to child elements, but this property is already assigned to a parent element? (I had this problem with fonts and colors).

Being unsure of what is going on with your CSS, you might be surprised to find that, for example, after you changed one property, half of your document inexplicably changed its color or indentation level. And there you are wasting time trying to apply a quick fix that most probably breaks something else. It is only then that you finally realize that the CSS refactoring time has come. Continue reading