Writing and programming, the same battle?

The main lines of technical writing have remained for decades: simple, concise writing and short sentences – the exact opposite of the way I write on a daily basis.

Luckily, I am also a developer. This can help a lot. Not only for logic, understanding software or languages dedicated to production, but mostly… to keep it short.

Similarities

Let’s not go so far as to say that programming in an object language is close to technical writing.

However, the focus is on functionality. We avoid rewriting the same piece of code 12 times, because we know very well that once it’s up and running, we’ll call it – not copy it! – from different locations.

We use a Framework, so we don’t start from scratch and benefit from the experience of those who have already been there.

And we’re going to choose the most suitable language for the software we’re developing, so for the users and for the platform.

Different languages, evolutions and backtracking

For example, I started by writing in C (the pure and hard one) and in Visual Basic (less pure). C taught me a certain algorithmic rigor. The “spaghetti” coding with its cross-references in all directions is a flaw in which one falls quickly. Same thing for a document: I don’t want to rewrite – see page 12, spaghetti documentation. And Visual Basic showed me that creating a nice interface on the basis of an existing application, like Access, is great: you simplify your life, you write a little function behind a button. But when you change version… pity, you can test everything again. It reminds me of Word. You change an image and you don’t understand why everything moves, you have to retry the whole chapter.

Then I discovered OpenRoad – it doesn’t make me any younger. The great thing about this language, or rather this development environment, was that it allowed me to develop in object, to have my data persist, to collaborate, and thus to benefit in the same repository from the code, collaborators’ windows, notes, and different versions.

Parenthesis on data persistence, it’s simple: we’d like what we put in our form to be stored in a database, in a file, etc.

Parenthesis closed; such an environment with the same company culture, the same way of working, industrial customers, it’s the awesome.

It’s great for a developer and for anyone who doesn’t like to do the same things 36 times over. The test routines are integrated, you avoid errors, you use the library and you concentrate on what you know how to do, create. Create rigorously and with a specific purpose, but anyone who likes to solve real problems understands me. The routine is over.

The 4×4 tools

Time advances, Borland had already invented the first RAD for the general public (Rapid Application Development), Microsoft Visual Studio is gaining momentum, Java allows to write only in one language for several platforms without modification and PHP is breaking through more and more. Let’s say that we are around 2006, an editor has just made progress with a tool that is very close to OpenROAD.

Since then, I still have a serious little doubt in a corner of my head; PHP is great. It’s very advanced, many Frameworks exist, a huge percentage of the web and applications work with it… but… creating the same interface with data persistence (very basic: a window and I enter the list of my contacts) is still and still visually very unfinished.

Symphony, Yii2 (sorry, they are Frameworks made by geniuses to work fast and well), are still very far from Visual Studio. I’ll skip the Docker’s and others that allow to separate the software from the data and much more. But it still bothers me, why do you have to put your hands in the code when it’s not useful? It’s really not useful when you create a web interface. Are you using a coding language again to layout an Indesign file? Of course not.

The purists will throw the first and subsequent stones at me: “we master better”, “it’s not for noobs”, etc.

Let’s put this in the context of technical writing and communication:

Use the right tool: Well, I want my content to be well separated from my layout for reuse. Let’s avoid Word (Visual Basic) right away, it’s pretty, full of buttons and functions, and you think everyone has mastered it. Certainly not, we lose time at the slightest deviation, and taking back content – text or image – is clearly not easy, except “copy – paste”.

For that, you choose a tool that goes away from a pretty interface and you switch to XMetal or others (I developed a nice one so I’ll talk about it: Synthetik). Very, very quickly, you realize that it’s finally simpler, even if the person who passes behind you will tend to say “well, I wouldn’t like to do what you do”. Yes, you would like it because it’s the right tool.

Use the right language: We don’t talk about C++, Java or English and French. We just express ourselves simply, clearly.

“Please press the purple button so that it changes color intermittently” versus “Press the red button until it flashes”. Similarly, a mechanic is not told what a 12 wrench is, they are told the torque and a pictogram for the tool.

Referencing your work: Yes, and there you can do things simply; “Copy_work_file_nov_jeanpaul.xml” or “211001_FR_winding solenoid_1245_v003_JPC.xml” is already more than enough in many cases: date backwards for easy sorting – I have my last modification date, language, BOM reference to find the assembly, version and author. In the file name, simply. We can do much better, but this is already a very good start.

Make your content elegant: The answer is more nuanced. It’s crucial that the client sees your work in its best light, whatever the medium and when coding, whatever the screen size too. The most accomplished content needs beautiful images, a beautiful layout. In this case, in order for the content to be well separated from the display, the formatting becomes a little more difficult.

We find ourselves with our PHP. Here, we’re talking about overlay style sheets, CSS. It’s not the sea to drink, but it’s not very visual. Still, we’re not going to take our files and paste them into Indesign, we’d be wasting too much effort.

So I’m going to do an article on CSS and markup separately.