Как написать репорт

One of the skills that business English students need to acquire/polish, is that of writing a report. Almost all the professionals have to deal with this from time to time, and knowing the right way to do it saves a lot of time, ensures the impact of the report is positive/as intended and is easily understood by the target audience.

Before we go any further, we need to clarify what a report is for. Normally, the target reader of a report is a person of higher authority (a manager, a client, etc). The purpose of a report is to inform someone about something in more detail. The style of the report is formal.

Here we’ll look at the most common type of a report for business English learners and some advice that can help you plan your lesson to better suit your students’ expectations.

The structure

Below you can see a company sample report based on which we’ll analyse the structure.

Your management is worried that the employees in your company are coming late to work every day. Your manager has asked you to write a report on the current issues related to this situation as the HR of the company. You must write about:

Write 180-200 words.

June 24, 2020

The purpose of this report is to look into the reason people are late for work, go through possible miscommunication issues and come up with possible solutions.

In order to narrow down the scope of the possible issues, I’ve conducted a survey with our team and the below mentioned issues have come to my attention.

Firstly, it’s necessary to introduce check-in cards, which people will swipe upon their entrance to the office premises

Secondly, an email should be sent out to the whole staff clarifying the working hours to be set from 9-6 with a 15 minutes grace period for those who are late.

See the survey results here.

As you can see from the sample report above, the first and the foremost things is to introduce the:

DOs

It helps to make your text more organized and reader-friendly. It is also a logical way of structuring ideas. Ideally, you’d use one paragraph for one idea. Also, make sure you address all the issues in your recommendations and provide solutions or action points. After all, the aim of a report, is not to merely state the facts, but also think of the possible way outs.

To make the report more coherent, use headings and titles. It will help the reader to more easily focus their attention. Headings will also make the text look neat and more professional.

You can use names and pronouns (I/he, etc.) or stick to impersonal, passive style. It all depends on whether you had taken an active part in forming the facts of the report or not. In any case, the style of the report should not vary. The way you start should be kept throughout all the text.

To get your readers attention prepare them with the amount of information they still need to read. Use linking phrases like (firstly, secondly, additionally, finally). Use enumeration as well, if you’re about to introduce more than one idea under the same heading.

Limit yourself to one idea per sentence. The shorter the sentences, the better its understanding and the more formal the style. After all, this is not an essay. Facts, figures, problems, solutions.

DON’Ts

Like stated above, the language of a report should be formal. “I suppose” and “delay” will be better than “I guess” and “put off”.

Avoid using short forms like (I’ve, I’d, etc.). Formal language includes using full words instead of their short counterparts.

Make sure you stick to your guns. Don’t overlap the report with non-relevant information. Keep it concise and to the point.

This is just one style of a report mostly used in everyday business writing, academic preparation courses (BEC) and language assessment slots. There are many other report samples (medical report, financial report, course progress report, etc.) All of them have their individual style and requirements, much depending on the company preferences and the sphere of expertise.

Try out this structure of report writing with your students and let us know how it works. It has always been a great success in my classrooms.

Как правильно составлять баг-репорты

Время на прочтение

Ответ на топик «Распространенные ошибки при составлении баг-репортов».

Правила оформления записей в баг-трекере в каждой компании свои — это зависит как от политики компании, технологии разработки, используемного баг-трекера, типа проекта и много чего еще. Но в любом случае хороший баг-репорт обладает определенными характеристиками.

Если кратко, то хороший баг-репорт позволяет:
1. воспроизвести проблему (это не всегда возможно, но надо стремиться).
2. понять, в чем проблема и какова ее важность.

Как написать хороший баг-репорт?
Для начала надо подготовиться. Если вы обнаружили баг, не стоит моментально бежать в баг-трекер и писать «ничего не работает!». Воспроизведите ошибку. Воспроизвелась? Отлично. Не воспроизвелась? Значит, что-то вы не учли. Вспоминайте, что делали.

Снова воспроизвелась? Ура! А теперь минимизируйте количество шагов для воспроизведения, удостоверьтесь, что нет ничего лишнего.
Если используются какие-то входные данные, удостоверьтесь, что и они не содержат лишнего (действительно ли весь этот здоровенный кусок текста роняет редактор, а не один символ из него?).
Когда вы поняли, какие именно данные и какие ваши действия приводят к проблеме, кратко сформулируйте ее суть — придумайте заголовок баг-репорта. Опишите проблему настолько подробно и конкретно, насколько позволяет заголовок, при этом не увлекаясь его длиной 🙂
Пример плохого заголовка: «Все виснет, когда я вставляю текст из буфера обмена»
Пример «более хорошего» заголовка: «Редактор зависает при вставке текста, содержащего символ N, из буфера обмена по Ctrl+V»
Allenary: Можно еще упомянуть принцип «Что? Где? Когда?». В большинстве случаев это помогает написать удачный заголовок/подробное описание, Например,
Что: неправильный расчет данных
Где: на странице NNN
Когда: после ввода а поле Y отрицательного значения.

Старайтесь не писать фразы типа «я кликаю на ссылку», «я нажимаю кнопку» и им подобные. И заголовок, и описания шагов — это руководство к действию для тех, кто будет исправлять проблему, поэтому лучше формулировать как «кликнуть на ссылку», «нажать на кнопку».

Теперь откройте баг-трекер, начните заполнять форму баг-репорта.
Запишите заголовок.

В каких-то баг-трекерах поля «Подробное описание» и «Шаги для воспроизведения» различаются, в каких-то — нет.

Если поле «Подробное описание» есть, опишите в нем проблему более подробно — уточните те детали, которые пришлось опустить в заголовке. Если вы понимаете, в чем причина проблемы (используется устаревшая формула для расчетов, не учитывается какое-то значение и т.д.) — тоже пишите все здесь. Если не знаете — лучше не гадайте.
Если в форме записи об ошибке нет отдельного поля Affect version (версия продукта, в котором проявляется проблема), то укажите версию здесь.

«Шаги для воспроизведения» — основное поле для заполнения в баг-репорте.
Запишите шаги, которые вы определили. Как уже было сказано, шагов должно быть необходимо и достаточно для воспроизведения проблемы. Лишние не пишите. Необходимых тоже не пропускайте 🙂
После описания шагов обязательно напишите результат — что получилось.
Далее здесь же опишите ожидаемый результат, если это необходимо. Конечно, не стоит писать «Редактор не падает», но если, например, результаты расчетов не соответствуют ожидаемым, то это надо указывать.
Таким образом, описание шагов для воспроизведения должно выглядеть как-то так:

Результат:
В поле Result отображается V1.

Ожидаемый результат:
В поле Result отображается V2.

Если требуются исходные файлы, данные, дампы и пр. — сразу приаттачьте. Само собой, файлы должны содержать только информацию, необходимую для воспроизведения ошибки. Подчистите все лишнее.
Если проблема с визуальным отображением, то скриншот обязателен — можно будет понять ошибку и без воспроизведения шагов. Khizhnyak: На скриншотах лучше указывать место с ошибкой. Стрелочкой или просто полосой контрастного цвета. Здорово ускоряет «чтение» скриншота.

Но вставлять скриншоты в каждый баг-репорт совершенно не обязательно: пожалуйста, не плодите лишних сущностей. Если он ничем не поможет в воспроизведении проблемы — не тратьте время на его изготовление.

Кстати, про видео воспроизведения ошибки: оно может помочь разве что для подтверждения, что проблема действительно есть, просто воспроизвести ее сложно. Но часто ли вы делаете запись экрана заранее? 🙂

По остальным полям.
Severity, Priority.
Наличие этих полей и значения в этих полях отличаются от багтрекера к багтрекеру.
Severity — это критичность бага с точки зрения тестировщика: фича, опечатка в тексте, мелкая проблема, значительная проблема, падение продукта, блокирующая проблема и пр.
Priority — приоритет, с которым проблема должна быть исправлена.
Если есть оба поля, то тестировщик, как правило, выставляет только Severity, а Priority — старший тестировщик/старший программист/менеджер или любой другой ответственный за это дело человек.
Если есть только одно поле, то выставляем его.
«Какой приоритет ставить багу?» На этот вопрос нет однозначного ответа, все зависит от каждого конкретного случая. Но старайтесь не увлекаться и не ставить всем багам подряд высокий или критичный приоритет, реально оценивайте их критичность для проекта.

Environment — есть во всех баг-трекерах. Это программно-аппаратное окружение, в котором проявляется проблема.
Укажите версию операционной системы, наличие сервис-паков, разрядность.
Если ваш проект зависит от каких-то компонентов — их наличие и версии обязательно! .NET, JRE/JDK и прочие SDK.
Интерпретируемый язык? Версию интерпретатора — обязательно!
Для веб-проектов — браузер, установленные плагины, если это влияет на работу проекта. Если что-то не работает в одном браузере, то проверьте, работает ли в остальных.

В какой версии исправить, на кого назначить — зависит от политики внутри компании. Не знаете, что поставить? Спросите коллегу.

Статья дополнена правильными замечаниями из комментариев.

Content of this article

A report is a form of writing that is systematic, organized, and often tries to define or analyze a problem or an event. The problem or event analyzed can also be within a body of literature belonging to either a single document or several documents. The sole purpose of a report is to objectively present readers with all the relevant information in relation to a particular issue. Writers are expected to shelve their personal feelings or shield themselves from issues that might render the report subjective because the use of reports is at times beyond aiming to impress the author’s readership. A report has three distinct attributes which help to distinguish it from other forms of writing.

The above makes report writing a different endeavor, but it is still a significant part of academic writing.

A report should always be:

Straying from the above disqualifies an author’s piece or article from being a report.

Report vs Essay. What is the difference

A report differs greatly from a conventional essay.

The above exquisitely and explicitly show the differences between essays and reports. Understanding these differences is the first step to learning how to write a report.

Topic selection for a report

Topic selection separates bad report writers from good report writers as well as from excellent report writers. In many instances, readers are attracted to certain documents because of their topics. Getting the right report topic is of the essence if writers are to maintain their readership. Many writers forget the issue of scope when selecting a topic. The scope is indeed an important consideration that calls for patience and careful consideration of the general subject suggested before settling on a specific report topic. Exceptional report writers understand the significance of scope and thus focus on specific aspects of a subject or topic before they decide on a topic. Writers are often advised to focus on the vitalities of a subject and only present that to their readers.

The above questions are indeed essential and help a writer to find or settle on a topic they are familiar with and also feel strongly about. Knowing what interests the readers is of course of the essence because it gifts the writer with a sense of direction and purpose. Finally, report writing needs to be factual and well cited. It is thus important to ensure the selected topic is adequately referenced for purposes of building a credible and reliable argument.

Below are some good topics for a report

As already said, a report structure is formal and must be strictly adhered to by all writers. Deviating from this structure only leads to reduced marks or a bored and angry audience.

Below are the elements that form the structure of a report:

Executive Summary/Abstract

An executive summary or an abstract mainly provides a summary of the entire report. While some writers write it immediately after commencing their report, it is always advisable to write it last. This section is of great importance and makes it easier for the readers to quickly understand the main points or the focus of the report.

Table of Contents

A table of contents is simply a list of all the sections the writer decided to include in their report. Its sole purpose is to prepare readers for what to expect when reading the report and also to make it easier for them to access some of the sections directly.

Introduction

Like other introductions, a report introduction ushers in the readers by providing them with a brief but accurate summary of the topic or issue under study. From the introduction, readers should be able to understand the writer’s focus or perspective.

Body

The body mainly contains the bulk of information which builds on or supports the thesis statement from the introduction. Unlike the body of essays, the body of a report can be divided into sections depending on the topic being reviewed. Some of the sections include a literature review, a methods section, a findings section, and finally a discussion of the findings section.

Conclusion and Recommendations

A report conclusion must be included, and it contains the inferences or the points the writer withdrew from the report. How to conclude a report is indeed essential because it provides writers with the opportunity of restating and insisting on their main point.

Recommendations are always included, and here the writer is expected to include their suggestions of how, for example, the investigation can be improved in the future or how a problem can be averted in the future. If in case the writer’s recommendations have financial associations, then he/she must provide estimations or the projected costs of whatever issue they were discussing in their report.

Reference list

Exceptional report writers consult journals and articles which are relevant to their topic. Later, these articles and journals need to be included under the reference list section. A reference list, therefore, contains all the materials the writer used to conduct their research.

Appendix

While this is not a mandatory inclusion, it adds to one’s analysis and should hence be included whenever necessary.

Once the writer has completed the report, it is important first to review it before submitting or printing it. Proofreading the finished report is indeed essential because it helps the writer to identify some of the mistakes they could have made. For example, one could have gotten some statistical facts wrong, and it is only through proofreading that such mistakes can be identified and corrected. Grammatical errors should also be avoided, and while currently there are software varieties that can help with this, the human mind is still miles ahead, and one should identify and correct such mistakes while proofreading. Reading the report to an audience can also help a writer to avoid some mistakes while also maintaining the focus and purpose of the report. Two heads will always be better than one and consulting one’s friends or co-workers could help a writer avoid re-writing the entire report in case it is found defective later.

Some good tips for a report writing

Report writing tips are readily available on the Internet.

Below are some of those tips:

Like the tips above, report writing help can be readily found on the Internet. However, it is essential to be involved in the entire process lest one gets what they did not ask for.

Чтобы написать bug report(отчет об ошибке) в Jira необходимо выполнить несколько действий, которые ты узнаешь на примере «боевой» жиры. Уверен, что общую концепцию поймешь.

Далее ты узнаешь:

Что такое Jira?

Jira — это система управления проектами и отслеживания задач, которая используется командами разработки программного обеспечения.

Она позволяет создавать, отслеживать и управлять задачами разработки, контролировать прогресс выполнения, планировать версии и релизы, обеспечивать коммуникацию и сотрудничество в команде, а также предоставляет отчетность и аналитику для анализа производительности проекта.

Jira помогает командам разработки эффективно управлять проектами и обеспечивать успешную доставку программного обеспечения.

Шаги для составления баг репорта:

1). Перейдите в Jira и нажмите кнопку «Создать».

2). Выберите тип проблемы «Ошибка» из списка вариантов.

3). Заполните поле сводки кратким описанием проблемы(summary), например такой шаблон: «путь до бага» — «какая проблема?», «когда?», «где?». Заголовок можно по разному строить.

4). В поле описания предоставьте подробное объяснение проблемы, и любые отображаемые сообщения об ошибках, например добавить логи и/или веб сокеты. Также можно прикрепить видео, скрины и другие файлы с необходимой информацией. Тут же можно указать окружение, где воспроизвелось или в ином специальном поле.

5). Напишите шаги для воспроизведения в специальное поле. Рекомендую в виде пронумерованного списка.

6). Прикрепите к проблеме любые соответствующие файлы, например снимки экрана и/или файлы журнала(логи, иные файлы), возможно еще какие либо ярлыки, компоненты.

7). Установите уровень приоритета проблемы в зависимости от серьезности ошибки и срочности ее исправления.

8.) По серьезности (Severity) бага в большинстве случаев, на практике, остаются пустым, по моему опыту, потому что тут разрабу виднее и то даже они часто оставляют это поле пустым.

9.) Назначьте проблему на разработчика или на другого члена команды, ответственному за дальнейшую судьбу ошибки (поле Assignee) на определенном этапе её решения.

Данный пункт, также зависит от договоренности внутри команды, потому что бывает данное поле остается пустым или назначается аналитик, PM, или сразу разработчик. В моем опыте было так, что я мог сразу бывает так, что несколько пр в сборку попало разработчика или аналитика(было, что человек был лицом совмещающий PM, PO и должность аналитика), а было назначаешь только менеджера или вообще пусто.

Заполните поле сводки кратким описанием проблемы.

10). Добавить информацию о спринте, также ниже версию приложения, где был найден баг и в какой версии будет исправляться он, если это известно. Чаще всего этот вопрос решает аналитик, поэтому у него можно уточнить.

Указывать номер билда и/или commit hash — НЕ обязательно. Тут не особо принципиально, потому что если в девелопе, то следующие билды тоже будут с багой. По хэшу коммита, а если их несколько в таске? Вряд ли угадаешь в каком косяк. Еще бывает так, что несколько PR в сборку попало. Данное требование может возникнуть в редких случаях, например удаленно надо подебажить разрабу. Но так не всегда. Тут скорее зависит от разработчика, потому что кому-то реально проще подебажить и найти по коммиту место, где поломалось.

11.) Можно установить связь с другой задачей, если такова имеется и присутствует необходимость, например можно установить связь с таской, которую тестировали и в ней нашли баг.

12). Нажмите кнопку «Создать», чтобы отправить отчет об ошибке.

Это основные шаги для работы с баг репортом, но шагов может быть больше. Главное, как по мне, это логи и шаги воспроизведения.

Важно предоставить, как можно больше подробностей в отчете об ошибке, чтобы помочь разработчику понять и воспроизвести проблему. Если вы знаете фронт или бэк, а именно умеете или хотя б немного понимаете в разработке, то можете добавить свое предложение по решению проблемы или например загуглить проблему и дать ссылку на решение.

Также необходимо быть как можно более конкретными при описании шагов по воспроизведению ошибки, так как это поможет разработчику определить основную причину проблемы и быстрее ее исправить. Если что-то в багах не понимаете, то уточняйте у разрабов/аналитиков.

Василий Волгин — full stack тестировщик