DEV Community: outsource.dev

Outsourcing software development to Romania

outsource.dev — Mon, 09 Aug 2021 09:21:53 +0000

If you are looking for a software companies in Bucharest, Romania for outsourcing development then keep reading. Whether you have an IT or software development project or are looking for staff augmentation then Bucharest has a lot to offer. Due to its location in Europe and only very small time zone difference, it is a popular location for nearshore outsourcing.

Nearshore suppliers in Romania have the key skills and experience for top projects in Blockchain, AI, Machine Learning ML, Augmented reality AR, virtual reality VR, websites, mobile applications, desktop applications, API and serverless, Business Intelligence (BI) and data analytics, embedded and IoT (internet of things) .

The Hackerrank 2020 survey shows developer salaries in Romania are on average 61% of the equivalent in the UK, and developers from Romania scored highly in the world in their challenges and report on Best Developers in the World.

Summary of basic information and facts on Romania to assist with researching outsourced software and IT development in Romania.

Romania has a population of 19 million people. Bucharest is the capital city. Others town in Romania are Cluj-Napoca , Timișoara ,Iași ,Constanța, Craiova ,Brașov ,Galați.

Romanian is the official language, with some people speaking Hungarian and some German speakers.

If you want to search for a supplier then a good place to start is a specialised directory of outsourcing suppliers.

96% of Employers don’t require SOLID software skills!

outsource.dev — Thu, 05 Aug 2021 15:59:01 +0000

Read the full article at gitconnected

Top time-saving tips using self-documenting software release notes

outsource.dev — Wed, 16 Jun 2021 09:29:08 +0000

When you realise the testers have signed off your latest release candidate and it is good to go, then the dread comes for the next necessary but hated task…. documentation.

As I got fed up with filling in and writing release notes for my teams over the years, we tried a few experiments at being lazy (i.e. intelligent task automation and not repeating work). A bit of upfront work to automate tasks is preferable to regular anguish and customers prefer it if the result is consistent and regular information.

The release note murky gap

Photo by mahdis mousavi on Unsplash
Why is it release notes fall into this murky gap between development and marketing teams? Who should write them? the developer? the product owner? the technical author? The arguments come thick and fast:

product owner — as they understand the features and issues.
developers — as they wrote the software so know it inside out.
team leader/scrum master — as the software guys are too techie and no-one understands them but it needs someone close to it.
testers — as they have a better understanding of how the features work in their entirety or how to reproduce the bugs the customer reported.
marketing — as it is another opportunity to promote the product and message the customers.
technical author — as it needs someone with some writing skills to decode the techie speak and explain it in plain english.

Timing of release notes

Photo by Nick Hillier on Unsplash

And the timing of creating and issuing release notes just as crucial:

do it (create and update) as each ticket (feature or bug) is fixed.
wait until end of the sprint and it has been neatly shown in a sprint review or demonstration.
wait until the release candidate has passed and is locked and loaded for deployment.
put it off and hope users don’t ask tricky questions.
do it a week after deployment and only document what the users complain about/ask about the most.

Level of detail

Photo by Michael Longmire on Unsplash

The next question is how much detail to put in a release note?:

top-level couple of sentences just explaining the goal and aim of the release e.g. security improvement
mid-level detail explaining the approximate areas or changes e.g. login page security improved and password strengthened
low-level detail explaining the exact area and change e.g. password strengthened by increasing minimum length from 8 characters to 12
low-level with justification explaining exact area and change and reason e.g. password strengthened by increasing minimum length from 8 characters to 12 to meet security guidance note ABC123 for UK government
low-level with justification and with traceability explaining exact area or change, reason and a reference identifier to trace it to any bug or change ticket e.g. BUG#123401 password strengthened by increasing minimum length from 8 characters to 12 to meet security guidance note ABC123 for UK government

An example of self-documenting software with in-built release notes

What was developed:

automated build pipeline that updated notes on every build
custom built tool to scan change lists in a release from the configuration management system and generate a list of tickets (bugs/changes) in a build.
list of tickets and build number formatted and appended to an HTML page.
HTML release notes page accessible within the web application from a Help > About page.
HTML release notes page includes: ticket number, 1 line summary of ticket, hyperlinked to the ticketing system to show full ticket.
HTML release notes page includes clear marker when an official external software release and its associated version number and date.

How was it used:

Testers received a new build for checking, logged into the web application and accessed the release note page. Clicked on each item to access its relevant testing, and added test notes to the ticket.
External users could access the release notes easily, however, hyperlinks to detailed tickets were disabled for them.

Learnings

The following items have been learnt the hard way or discovered over a period of time by the author and need careful consideration:

An automated system to generate release notes has many benefits and the payback time is very short.

Some changes in a build are hidden through feature flags (dark releases) and may need to be hidden in a release note for certain users to avoid confusion.
Original ticket titles written by end-users that are included in release notes are not clear and often refer to the wrong thing.
Ticket titles need to be consistent through use of naming when referring to the product, modules, task and if they describe the symptom, problem or solution.
Software developers don’t write clear release notes for end users.
Someone in the team needs to be responsible for consistency, cleansing and reviewing of change ticket titles.
Any step that requires manual intervention will be late or go wrong at some point.
As teams become more efficient and deploy faster than release notes become more critical.
Release notes need to be easily accessible and in a suitable format.
Release notes that are vague or missing information are not trusted and have no value, so you may as well not produce them.

Tips

Generation of release notes should be fully automated for every build.
Release notes need to be timely and generated at the time of the build or release.
There should be clarity in the release notes on naming and dates for external releases and internal builds.
Having easy access to release notes at the point of use i.e. within the application is beneficial for users.
Having easy access to release notes prior to the installation of any software update is beneficial for IT staff.
Release notes should include details of all changes including references, dates, areas of change, type of change (defect or feature request or modification).
Certain confidential changes may need to be filtered out based on the role of the reader or omitted entirely when generating the details.
Release notes need to explain where a change has been made in a simple fashion (to allow readers to decide if the change impacts them and if they need to dig deeper or not).
Release notes should hyperlink to more detailed information based upon the role of the user.
Any hyperlinks to tickets should go through a middle layer/proxy to handle any future changes to the ticketing system.
Release notes need to be augmented by user manuals/online guides/feature explanations.

More About The Author

Greg is an experienced software professional and CTO at outsource.dev , having worked in several businesses he is now passionate about helping others succeed in software development, management, and outsourcing.

If you enjoyed this article then please like it and follow me.

Code as diagrams - What's the point?

outsource.dev — Tue, 15 Jun 2021 08:11:33 +0000

You often hear the phrase “diagrams as code” referring to using a text editor to write some code that can be parsed to create a diagram rather than using a graphical editor and UI to create a diagram. If however, you parse real source code to create a diagram then you are reverse engineering it. So what value does “code as diagrams” give us as engineers?

The simplicity of the structure according to Monet

The evening scene in the painting by Monet of San Giorgio Maggiore At Dusk shows the outline of the building, with no details on the building just a dark shape. A simple graphical representation of the calling structure of a piece of software is often shown as a simple A calls B, then B calls C. On initial inspection, this basic diagram doesn’t seem to offer much value until you have seen lots of them and then it becomes easy to spot the problems. In reality, this is the human eye and mind doing complexity analysis which could be done with a command-line tool that highlights all modules over a certain value.

Beauty in the detail according to Fazio

The Hyperrealistic hand drawings that look like photos by Diego Fazio offer an amazing level of precision and detail that give a purity in the level of depth and perception. It is possible to generate diagrams of software structure that include a significant amount of detail to complete the overall picture. This extra information can include:

sequence the functions are called in
parameters passed into functions
values returned
whether functions are public or private Standard diagrams that include more details are:
UML
Yourdon DeMarco structure charts, showing data and control flows. -Jackson charts — Call charts that are read top-down and left to right to show the sequence that functions are called. The advantage of extra information is it allows the reader to get a fuller picture of what is going on. However, it adds clutter to the diagram and if the focus of the chart is not kept to a few modules then it becomes hard to render and view due to the sheer volume of information and complexity in trying to lay it out.

Clarity through movement

The great wave off kanagawa by Katsushika Hokusai is a block print and shows the motion of a crashing wave capturing its dynamic movement. Rather than statically analyse the call structure of software it is also possible to scan and monitor a dynamically operating piece of software. This can then show the call tree for that specific execution of the code and its paths as well as augment it with additional information. This diagram using pycalltree shows how many times each function was called (number on the arrow) and its execution time (within each box). Additionally, it has graphically grouped functions into their packages showing the logical cohesion of functions.

Deep and narrow like the Mariana Trench

A deep and narrow structure is normally a cause for concern and further investigation. All the modules show a lack of reuse, and layers typically indicate slow software with lots of extra unnecessary calls.

Wide and shallow like the Platte River

The wide and shallow structure could be typical of a package with a large number of API endpoints. Shallow depth indicates the simplicity of each endpoint however little commonality of lower layers shows a lack of coupling within the package.

Wide fan-out like the Nile Delta

A wide fan-out typically identifies a module doing control aspects, such as implementing a finite state machine or acting as an API access point which is dependent on data for guiding the subsequent action.

Fan-out then fan-in like an Egg

Typically shows a reasonable structure with perhaps a simple public API or interface then a layer to handle logic with only a few lower-level routines for data or device access.

Flowchart Diagrams

Rather than showing the hierarchial calling tree of a module it can be useful to visualise the flow of software in a flowchart. These types of diagrams have been around for a long time which has the advantage that everyone knows how to read them. Although there are some formal standards, such as the 1985 ISO5807, the symbols of a square process box and a diamond decision box are well known. Lots of tools support the basic symbols e.g. MS Word and Powerpoint, as well as other non-standard but easily understandable ones with a more pictorial representation of a device or logic.

ISO5807 , 1985, flowchart symbols, https://www.iso.org/standard/11955.html

Nassi-Schneidermann diagram

Another style of diagram to show flow was developed in 1972 by Nassi and Schnediermann, sometimes called structograms. This style of diagram is not often used. However, it does uphold good practice by not being able to represent “GOTO” commands.

How to draw Nassi-Schneidermann diagrams in Excel — https://www.breezetree.com/articles/nassi-shneiderman-diagram/

Code size as Treemaps (Oak or Beech or Maple)

There are a variety of charts and diagrams for showing the relative size of software modules in a solution. The size of each package or function is computed as a % of the entire size and then shown as a rectangular block on a larger square that represents the entire size (100%).

Tree maps — https://en.wikipedia.org/wiki/Treemapping

Tools

Here are a few tools (focused on Python) as an example, rather than a comprehensive list:

pyflowchart — https://pypi.org/project/pyflowchart/ parses static Python code to create a structured text file that can be rendered into a diagram showing the flow of the code.
pycallcallgraph — https://pycallgraph.readthedocs.io/en/master/index.html# — traces dynamic execution of python software to produce a call tree.
pynsource — https://github.com/abulka/pynsource — parses static python code to produce UML class diagram, see in action at gituml
pylint and pyreverse — https://www.pylint.org/
Excel for Nassi-Schneidermann charts
Excel for treemap charts

Final Thoughts on getting the right perspective

All of the diagrams discussed have a benefit to the reader and the key is being able to see the required view or views, i.e. having the right tool for the job and at the right level of resolution and granularity (rather than google earth at maximum zoom). There is a range of tools on the market which either need to be chained together to get a variety of views or only give a single outlook. The top end of the toolchain with CASE tools/design tools gives a more holistic solution but there is not a wide industry adoption of a common approach or product.

Final thoughts on what is the right tool for the job?

When reverse engineering a software application we currently use a variety of separate and disparate tools. These tools can be connected and sequenced by a CI/CD build pipeline and the output viewed using text editors, image viewers, and a browser but it doesn’t feel very integrated. As modern-day code development platforms have become more advanced, we have evolved from notepad.exe and vi to more complex IDE environments with a myriad of customised plugins. Having a real-time view of these various perspectives with a code editing environment feels like the holistic way to go, the equivalent of a holo-lens visor for a technician working on a complex nuclear reactor who needs to know which wire to cut.

More About The Author

If you enjoyed this article then please like it and follow me.

What do self documenting software and doors have in common?

outsource.dev — Sun, 13 Jun 2021 11:08:02 +0000

Self-documentation — is documentation in a suitable form, typically label, signs, or simple instructions embedded, attached, or nearby to the device. This allows the device to be used, operated, changed, and repaired by following the instructions without having to hunt for some other form of documentation.
For those of you that think DOORS is some sort of new operating system or methodology then prepare to be amused. I thought it would be fun to explain what self-documentation is, and various styles through examples. The easiest device and familiar to us all is a door. The standard operation and use of a door are known to everyone however self-documentation can be essential in certain situations. In the following images each door has explicit documentation or implicit description, that are summarised in the titles. As you view each one try and contemplate what the equivalent “label, sign, or documentation” would be in the world of software source code.

Forms of self-documented software

readme.txt — The humble start of documentation, a single ASCII text file left in a folder, containing as much guidance to the next visitor as possible. Unstructured and with limited capability to include diagrams or complex structures due to the primitive format. However the saving grace is that it it stands the test of time and can be accessed and viewed without any complex supporting tool set. Infact it may just include the instructions for bootstrapping and downloading enough tooling to view the rest of the project.
readme.md — The next evolution of readme.txt using markdown formatting which can be added using any text editor. Supporting the ability to render a more visualy appealing version of the content including titles, bullets, code formatting, and hyperlinks.
filenames — have filenames that have meaningful value in their description. They describe the contents of the file or the purpose of the module. No one likes a project with files called mod1.c, mod2.c, mod3.c. Having a file called DRV-PCB123REV2.C that is a driver for a specific embedded circuit board of part number 123 and revision 2 is clear and easy to find especially if their is a file naming convention.
file headers — free format comments at the top of a file to explain the context of the file in a high level form.
keywords — can be used to identify a location in the source code where a certain type of information should be automatically added, typically by the configuration management system such as subversion or git. This information could be a basic history of commits, the author, date of file creation or last edit.
function headers — free format comments at the start of a method or function to explain the high level purpose of the code, its structure, variables and processing flow.
javadoc style comments — the javadoc style comments within a delimited and structured style to allow automatic extraction (and insertion) of text.
code comments — comments on or next to lines of complex or ambiguous source code.
naming conventions — longer and more descriptive explanation of the variable or function. e.g. Total = Price + Tax; is a lot clearer than i=j+k; Originally when code size was limited by storage systems programmers would write in a compact and abbreviated format (for a language that suports abbreviating on a big scale check out the MUMPS /M lanaguage). As hardware storage devices and languages developed then longer names for variables and functions were supported however it requires discipline to use them. Hungarian notation is a style that includes describing the type of a variable, useful in some situations but can overcomplicate the naming and make readability harder e.g. iage (is for age, and has an ‘i’ prefix indicating it is an integer).
names not magic numbers — explain the reason for a choice of a number, to allow the reader to understand it derivation, importance and units. eg timeout = 30 doesn’t explain why the value of 30 was picked, and if it occurs in multiple places in the code it is also hard to understand if the reasons are the same. Whereas timeout = RFC7231_REQUEST_TIMEOUT_IN_SECONDS conveys a lot more information or timeout = RFC7231_REQUEST_TIMEOUT_IN_SECONDS — ADJUSTMENT_FOR_DEVICE_AB123_THAT_IS_NOT_RFC_COMPLIANT shows the pure design and the practical adjustment that has had to be implemented for compatibility reasons.
whitespace — use of whitespace around source code can improve the readability, and also help delineate the end of one method and start of another.
tags — keywords left as comments are easy to search for and indicate a location where further work is required such as TODO, FIXME.
programming language — certain languages such as gherkin used for BDD allow natural english to be used with only minimal conventions and keywords to add structure to it.

In Summary

There is a lot the author of software can do to make the purpose and reasons for their decisions clearer to the next person to look and work on the code. By paying attention to all of the above items the software can be self-documented and be less reliant on other external sources of information. This is a benefit as separate documentation can be hard to find, access and relate to in the target context.

More About The Author

If you enjoyed this article then please like it and follow me.

Brief History and Evolution of the Concept

outsource.dev — Sun, 13 Jun 2021 10:56:32 +0000

Overview

In this first article I want to set the scene by outlining what living documentation is, and the types and flows of knowledge in the engineering process. Future articles will cover currently available tooling and options.

So let's get started and cover some basics to all get a common understanding on:

Definition of Living Documentation
Forward and reverse engineering
Maintenance and customer documentation
Design evolution
History of living documentation

Definition Of Living Documentation

The key elements of living documentation are:

Living — it is up to date and reflects the current state of the software
Documentation — it is a collection of descriptions regarding the requirements, architecture, design, implementation, and operation of the software system.

There is no formal definition covering:

What it should include
How it should be formatted
How it should be structured
How it should be maintained By formal, I mean an ISO or ANSI standard, or even a book that has been accepted as best practice, or a tool that has gained widespread acceptance and offers a universal solution.

This doesn’t mean that these topics haven’t been discussed, requirements clarified, or point solutions available.

Cyrille Martraire in his book describes the key principles of living documentation as being:

Reliable
Minimal work to produce
Collaborative
Insightful

At this stage, it is worth looking at traditional engineering practices and the types of documentation produced to set the scope.

Forward Engineering

In traditional forward engineering (left to right) tasks are done in a sequence. This is true for waterfall where an entire stage is completed for the entire product before the next stage starts. The output from one phase is typically documentation (as a discrete document or within a tool) and this forms the input to the next stage. The final output is source code which may or may not include the output from the previous design phase. This design may be a simplified text-only description of the design, such as function descriptions or pseudocode. For agile projects then the process is still similar but executed on very small amounts of software, and several of these can be in development concurrently.

Reverse Engineering

Reverse engineering is often associated with situations where a team is trying to modify an undocumented software product. Large products are hard to understand so a tool may be used to statically analyse the codebase and simplify it into hierarchical function calls and classes. The interpretation of the design can be a mix of diagrams and text and include relevant code extracts or references. In addition, these tools can highlight anomalies, such as functions and methods that are not called, variables that don’ appear to be ever used.

Maintenance

When software moves into the support and maintenance phase then pressure from customers and the need for rapid response tends to decrease the amount of design and increase reliance on helpdesk tickets.

Customer documentation

There is also a requirement for some documentation for customers, such as release notes, FAQs, user manuals, and online help. This is typically done by a technical author and is based upon real-life use of the product, company standards for customer documentation, information from helpdesk tickets, internal release notes, and specifications. Software source code traditionally never feeds into this activity as the authoring team is unlikely to be able to understand it, and it is unlikely to include design information in a format that can be easily understood.

Design evolution

Photo by Eugene Zhyvchik on Unsplash

The world of software design has gone through various steps in its evolution and the BDD transition is a critical connecting piece in the living documents puzzle. These design steps can be summarised below:

TDD Test Driven Design — write a test, run the software, watch the test fail, write software so the test will pass
MDD Model Drive Design — focuses on abstract representation rather than the software concepts, and favoured large CASE (Computer-Aided Software Engineering) tools in the 1980s and used UML to describe details.
DDD Domain-Driven Design — includes knowledge of that domain, terminology, context, and its boundaries. DDD is considered more abstract than MDD.
BDD Behaviour Driven Design — a way to define the dynamic behaviour of a system using domain-specific terms such that the requirements can be traced to test scripts and executed

BDD is arguably one of the biggest steps as the simple format for documenting features and scenarios using Given-When-Then syntax from a simple ASCII text file. This simplicity allows people to interact with it using any number of standard tools and also for it to be automated and transcribed into instructions for a test automation framework.

A brief history of the journey to Living Documentation

-1921 Flow process chart presented by Frank and Lillian Gilbreth
-1963 Flow chart standard by American Standards Association, Article on Techniques of Flowcharting by Louis A. Schultheiss
-1970's Data Flow Diagrams and Context Diagrams, Yourdon and Constantine
-1975 book Principles of Program Design, Jackson.
-1985 Sidecar files used in AmigaOS with Meta data, ISO5807 standard for flow chart symbols
-1997 Doxygen tool started, UML v1.1
-2003 JBehave (replacement for JUnit) developed, JavaDoc released by Sun, book Domain-Driven Design by Eric Evans[5]
-2004 BPMN v1.0 released,
-2005 RSpec (BDD for Ruby)
-2006 Article in Better Software magazine by Dan North on BDD [4]
-2008 Cucumber (BDD for Ruby)
-2009 Specflow (BDD for .Net)
-2011 Book Specification by Example[1] [3]
-2018 C4 Architecture Model published
-2019 Book Living Documentation[2]

[1] Specification by Example, Gojko Adzic,(2011) ISBN 9781617290084
[2] Living Documentation, Cyrille Martraire (2019) ISBN 9780134689326
[3] Reflection 10 years on (2021) https://gojko.net/2020/03/17/sbe-10-years.html
[4] https://dannorth.net/introducing-bdd/
[5] Domain-Driven Design: Tackling Complexity in
the Heart of Software by Eric Evans

More About The Author

If you enjoyed this article then please like it and follow me.

Book review — Living Documentation

outsource.dev — Sat, 12 Jun 2021 13:09:37 +0000

This is a solid reference book, with a substantial content of 480 pages in a hard back cover. It has a picture of the pipes from the Pompidou centre in France on the cover, which is relevant due to the colour coding of the types of pipes which is an example of self documentation. Cyrille Martraire is a CTO and speaker at conferences on various aspects regarding software development. There is a lack of material in this area so this is a welcome addition to the bookshelf. It heavily references DDD Domain Driven Design, BDD Behaviour Driven Design and Java examples as well as a variety of tools that can be assembled to create a documentation toolkit. It is not a magic bullet and doesn’t include a secret sauce recipe, but it does explain a wide range of concepts and show real life examples which should help the reader start exploring areas further.

There are 15 chapters in this book:

Chapter 1 — Rethinking Documentation — Great introduction to the topic of Living Documentation. It explains self-documentation, and how the principles relate and co-exist with AGILE, BDD and DD. The depth of the tables listing these concepts as patterns show the author knows his subject extensively.
Chapter 2 — Behaviour Driven Development as an example of Living Specification — A lot shorter than chapter 1 but gives an introduction to Given-When-Then syntax from BDD and various tools such as Cucumber and Specflow.
Chapter 3- Knowledge Exploitation– Explains sequencing of information flow and use of automation. Snippets of Java code start to appear as examples.
Chapter 4 — Knowledge Augmentation — This chapter makes a lot of sense and describes additional sources of information either annotated inside the code or externally (in a database or sidecar file). The simple sidecar file eg algorithm.txt to support a code module algorithm.java that has a similar name is explained. Annotation and tags are described with heavy references to java examples.
Chapter 5 — Living Curation: Identifying Authorative Knowledge — Concepts of sightseeing maps and identifying good code are revealed, along with consistency and naming conventions.
Chapter 6 — Automating Documentation — A really useful section as it highlights some though provoking items. Such as a massive class diagram for all classes in a codebase, where as it is easier for the reader to just see a few related to the module of interest. A bit like looking at the entire world on a detailed map when you only want to drive up the road and being overwhelmed by the scale of it all. This chapter also covers hexagonal architecture diagrams as a different way to look at the world The examples of pictures produced by static tools that reverse engineer code were extremely interesting. This shows a general concept and examples without Java specific syntax.
Chapter 7 — Runtime Documentation — Traffic tracing on distributed systems and event sourcing are explained as ways to augment knowledge from the system when it is running
Chapter 8 — Refactorable Documentation — Code conventions, naming and types are covered in the realm of code as documentation.
Chapter 9 — Stable Documentation — Stable and unstable information and how it can be documented. This allows a reader to consider refactoring a document eg readme.txt file to contain stable information and hence require updates less often.
Chapter 10 — Avoiding Traditional Documentation — A variety of scenarios and example on techniques to try and avoid documentation through other routes e.g. conversations based on the value and duration of the information.
Chapter 11 — Beyond Documentation — Living Design — Some good examples and tips in this chapter, including “shameful documentation”. The main message being when you make clear documentation the design becomes transparent. Has some really simple but effective ideas for crudely scanning code as a signature survey.
Chapter 12 — Living Architecture Documentation — Good coverage of design and architecture, and reasons for decisions. Some good examples of ADRs, and architecture templates. Some pragmatic tips on minimising documentation using a codex. A really useful section with lots of hints and ideas.
Chapter 13 — Introducing Living Documentation to a new environment — This is more managerial advice on how to introduce the concepts to a business. This feels like it has some solid experience behind it and tips learnt the hard way. It advocates starting gently and building up, which definitely feels like good advice. It even includes how to handle common objections. This managerial level is in contrast to the detailed java code snippets earlier in the book and shows the flexibility of the author.
Chapter 14 — Documenting Legacy Applications — Covers annotation, augmentation and rearranging items to be more understandable.
Chapter 15 — Extra : Conspicuous Documentation — Covers a lot of interesting items that don’t fit neatly in anywhere else. From low fidelity information and diagrams and their benefits, concrete examples of scenarios and problems to get real deep dive detail and tips on how to prepare for an interactive workshop. It also covers lot of other media and types of documents such as news, release notes, APIs. Again the shaded tip boxes work really well and draw the readers eye to salient points.

The 15 chapters flow easily and have been well considered. The titles are all generic and refer to Living Documentation in a wide sense, however code examples are in Java. There are a variety of hand drawn sketches through the book to lighten the mood, these don’t distract and are relevant to the areas they are placed. There are numerous easy to understand and believable examples, all the sketches are clear and appropriate and every topic feels like it has been thoroughly covered. There are shaded tip boxes and throughout the text hints to follow up for keen readers with specific books or papers on a topic. This is a great way to keep the flow going and the text to a sensible length but give signposts to avid enthusiasts on how they can find out more on a specialised area.

Summary

Having read this book I found myself taking notes as I worked through it because having scanned the book I couldn’t find key summaries. I was looking for a list of key information that I could refer to at a later stage as a full reference on Living Documentation, in particular:

List of tools and websites
List of books, authors and their topics There are numerous great links and tips scattered through the document but it would have been really helpful to have a condensed list in an appendix at the end of the book. There are a lot of examples with Java in this book, perhaps too much java or at least not enough generic description of ideas and concept before a practical example in Java. As there are relatively few books on the Living Documentation topic area this one stands out, so is a great reference piece. It could have been titled “Living Documentation for Java Programmers” which reflects how it is written. Living Documentation with some Java Examples would have been better or even Living Documentation A Complete Reference but it wasn’t to be.

No matter, these are minor points as this is an excellent document and key reading for anyone interested in the subject area and the bonus is it an easy read, light and airy in style but deep in content. Due to the lack of other books this one stands out and I was enthused and invigorated by reading it. I have no hesitation in recommending it, and hope if it is ever revised then there is opportunity to make it really great and a handy desktop reference guide for everyone.

Details of Book on Living Documentation

Living Documentation by Cyrille Martraire June 2019
480 Pages
Published by Addison-Wesley
ISBN 978–0134689326
Buy on Amazon

How to outsource to Vietnam

outsource.dev — Fri, 11 Jun 2021 10:44:50 +0000

How to successfully outsource software development and IT projects to Vietnam is the question that is very topical now. With changes in world, more businesses than ever are asking the question of whether they should try outsourcing in any of its flavours – onshore, offshore, nearshore ,or hybrid. Hence senior management, CIO, CTO or team leaders are being asked questions on how to make it work.

Photo by Peter Nguyen on Unsplash

Basic Facts on Vietnam

Vietnam is in East ASIA and a time zone of UTC+7 hours with no adjustment for DST. It has transformed over the last 30 years into a dynamic part of the region. It has a population of 96.5 million and expected to grow to 120 million by 2050 according to Worldbank. Health and living standards have improved with life expectancy up by 6.3 years since 1990 to 70.5 years.

Education and Proficiency In English

As the Latin alphabet is used then Vietnamese people find it straight forward to learn English. English is now mandatory in most schools in Vietnam with students reaching B1 level on the CEFR standard.

Skilled Engineers

There are over 160 public and private universities in Vietnam. 60% of the population are under the age of 30 and over 25,000 engineers graduate each year from University.

Outsourcing to Vietnam

Ho Chi Minh city has been named one of the best cities in the world for software outsourcing due to cost.

VINASA is the Vietnam Software Association. Software and IT Services Association established in 2002 and based in Hanoi. It has grown to more than 360 member enterprises by 2018 mainly based in Hanoi and Ho Chi Minh City.

Costs

A 2019 report on labour costs shows that Vietnam is slightly cheaper than India and almost half the cost of China.

Comparison of the hourly cost of a programmer in 2019 was:

-Vietnam $25-$35
-India $28-$42
-China $37-$60

The rate for a mid-level developer across the world regions by comparison was:

-USA $132-$140
-Europe $35-$56
-Latin America $30-$52
-Asia $24-$35

How to outsource to Vietnam

Start by scoping the project and a description of the goals and objectives, follow a guide on how to do this if this is your first time outsourcing. It is easier to use a specialised supplier directory than a generic search engine to create a short list of candidate companies. Then contact the business with an outline of your proposed project and start to get further details on their business. It is important to check technical capability, availability of staff and equipment and processes for development and communication. Also try to find a business that has a similar way of working and culture to make it easier to interact. Take the time to discover a long term partner you can keep working with on future projects that bring a range of benefits as well as cost savings.

What is ITO?

outsource.dev — Fri, 11 Jun 2021 10:31:41 +0000

What is IT Outsourcing (ITO)?

The world of outsourcing has a variety of terminology and one term that is not broadly understood is ITO or IT outsourcing.

When it comes to outsourcing one term that is widely known is BPO, Business Process Outsourcing.

BPO is the outsourcing of an essential function, this could be an entire department such as HR or a specific function that is performed e.g. payroll. Often BPO is associated with call centres, customer service and back-office tasks.

In a similar fashion,

ITO ( describes IT outsourcing of some or all of an IT function such as software development, hosting, applications or infrastructure to a third party supplier.

IT Outsourcing (ITO) Models

There are also a variety of terms used to describe various IT outsourcing models:

onshore — The supplier is based in the same region/country/timezone as the client. For example, a UK client dealing with a UK supplier.
hybrid — The majority of the supplier team is based offshore but a small number of supplier staff are located in the client region, possibly the same office for ease of communication and access. For example, a UK client with a few UK based supplier staff and the main team based in India.
nearshore — The supplier team is based in a near geographic region to the client, so time zone differences are small and travel times small. For example, a UK client dealing with a European supplier.
offshore — The supplier is in a different time zone a significant distance from the client. benefits are often cost and team availability. For example, a UK client dealing with an Indian supplier.

IT Outsourcing (ITO) Charging Models

As with any business, there are also a variety of charging models and contract types, including:

Fixed price — Predetermined fixed amount to deliver the work regardless of manpower effort actually used or costs of any services or materials. Requires a precise definition of the requirements upfront. If the client does not have a suitably detailed set of documented requirements or there are areas of high risk the supplier could do an initial piece of work to document the requirements and understand the level of risk before providing a quotation for the main project.
Time and Materials — Sometimes referred to as cost-plus. The supplier records the amount of effort spent on the project (typically through timesheets), and tracks all expenses incurred for materials and services and then invoice the client at the rate that was agreed at the start of the project. Any risks that result in time overrun or extra effort are passed to the client. Does not need all requirements to be defined at the start of the project, and most suitable for agile methodology projects.
Augmentation — The client wants a set number of staff for typically a long period of time to perform tasks. Tasks and work don’t have to be defined at the start of the engagement, typically the types of work and task are known so that appropriately skilled staff can be provided by the supplier.

Why outsource software development and IT projects?

There a variety of reasons that IT outsourcing is used:

cost — using resources from another geography may have benefits of lower direct cost
management — no management effort to hire, recruit, retain, pay staff and ongoing management is provided from the supplier
short term project — the ability to add extra staff for a specific project reduces costs and impact on a business, and there is no issue at the end of the project with having to reallocate staff.
specialist skills — it may be that a new product or project requires specialist staff for a specific time or task which would not warrant employing them on a full-time basis.
staff augmentation — if there is a need to scale quickly or add a new department for a new activity, eg adding a support or maintenance team for a finished project then.
clarity of costs — by having an external supplier do a specific task it is a lot easier to track costs, and hence manage your profits, especially if work is being done for a client.

How to Find an IT Outsourcing (ITO) Supplier

There a variety of ways to find an ITO supplier.

Recommendation — from a colleague or friend
Manually searching the internet — use a search engine then create a list of possible suppliers.
Use a specialist directory — by using a business directory that is specialised in a niche sector you can ensure you are only looking at shorter lists of possible suppliers and search for specific criteria. A good place to start is https://outsource.dev

DEV Community: outsource.dev

Outsourcing software development to Romania

96% of Employers don’t require SOLID software skills!

Top time-saving tips using self-documenting software release notes

The release note murky gap

Timing of release notes

Level of detail

An example of self-documenting software with in-built release notes

Learnings

Tips

More About The Author

Code as diagrams - What's the point?

The simplicity of the structure according to Monet

Beauty in the detail according to Fazio

Clarity through movement

Deep and narrow like the Mariana Trench

Wide and shallow like the Platte River

Wide fan-out like the Nile Delta

Fan-out then fan-in like an Egg

Flowchart Diagrams

Nassi-Schneidermann diagram

Code size as Treemaps (Oak or Beech or Maple)

Tools

Final Thoughts on getting the right perspective

Final thoughts on what is the right tool for the job?

More About The Author

What do self documenting software and doors have in common?

Forms of self-documented software

In Summary

Further Reading

More About The Author

Brief History and Evolution of the Concept

Overview

Definition Of Living Documentation

Forward Engineering

Reverse Engineering

Maintenance

Customer documentation

Design evolution

A brief history of the journey to Living Documentation

Further Reading

More About The Author

Book review — Living Documentation

Summary

Details of Book on Living Documentation

How to outsource to Vietnam

Basic Facts on Vietnam

Education and Proficiency In English

Skilled Engineers

Outsourcing to Vietnam

Costs

How to outsource to Vietnam

Further Reading

What is ITO?

What is IT Outsourcing (ITO)?

IT Outsourcing (ITO) Models

IT Outsourcing (ITO) Charging Models

Why outsource software development and IT projects?

How to Find an IT Outsourcing (ITO) Supplier