__ __ _ _ __ _
| \/ | __ _ _ __ ___ ___| | | |/ /_ __ _____ _| |__ _____ __
| |\/| |/ _` | '__/ __/ _ \ | | ' /| '_ \ / _ \ \ /\ / / '_ \ / _ \ \ /\ / /
| | | | (_| | | | (_| __/ | | . \| | | | (_) \ V V /| | | | (_) \ V V /
|_| |_|\__,_|_| \___\___|_| |_|\_\_| |_|\___/ \_/\_/ |_| |_|\___/ \_/\_/
Provide an example software project for a Salesperson persona 'Marcel' to gain knowledge and help to identify business opportunities.
This example project aims to provide knowledge to a persona named Marcel.
Marcel starts at his company as a Sales representative. Although he is an experienced salesperson with many years on the job, he only has a base knowledge of IT services. Since his company focuses on providing custom enterprise software solutions, one of Marcel's tasks is to gain general knowledge about the latter area.
The Marcel Knowledge project reflects many exemplary services his company provides in a simplified and documented form (e.g., UX Design, Frontend, Backend, AI-generated content and data or Data Engineering). The keep it very understandable: The example project is a quiz game.
With this example project, Marcel receives a long-term reference for look-up to gain and extend his knowledge. Through his career at his company this example project can always serve as a base to explain new concepts relevant to know for his work as a Salesperson. Though the aim is never to enable Marcel to provide such services in person having a concept of what he/she is selling will always help.
This Githup repository (repo) is the conceptual main project for the Marcel Know How Example Project. It contains of:
- General documentation to be readable by the persona Marcel (this README.md)
- A python script to create AI content (questions and images) populated to the frontend and database (see AI Content Generation Doc)
- A guide on how to install the local tools on windows
The following other repos belong to this project:
Marcel's company received the order to build an MVP (Minimal Viable Product) for a fictional business case. The project has already started and is in a developed state to be looked at with certain limitations (as also listed below).
Simplified and fictional: A customer wants to provide an open quiz game with the theme of European history. If the game app gains more then 1,000,000 users the customer wants to extend and monetize the app by offering a "Pro subscriptions" for other themes with a payment of 5 Dollar per yearly subscription and the expectation of 1% conversion.
For having an easy but also realistic stack tech for Marcel's company the following stack is used:
- Frontend: React with Typescript and Material UI
- Backend: Python with FastAPI
- Database: Neo4j (Mainly for the easier to understand concept and the included browser for visualization)
- DevOps: Docker, Docker Compose, GitHub Actions, Azure Container Registry
- Cloud: Azure Container Apps
- AI: For quiz question and illustration generation OpenAI's GPT-4 and Stable Ai's Stable Diffusion
All reposs of this project reflect the tech stack.
For a Salesperson it is not relevant to learn how such a project is implemented in detail. But it is important to have a high-level concept of what belongs to providing a software project to find and identify business opportunities. When talking to a customer the following paragraphs provide a high level overview of the main services Marcel's company provides and how the services are refelected by this example project. The paragraphs also contain typical questions and issues to be discussed a salesperson can rais to drive a conversation. Though Marcel should remember that its his company's experts who have the detailed expertise and can be brought in to answer the potential customer's questions.
A salesperson should understand what kind of business drivers are relevant for the customer. This helps not only to ask good questions but also to inspire the customer with new ideas and the best case.
Taken the scenario descibed above and assuming Marcel only knows the business case but there is no order or project yet a typical approach would be to suggest starting with an MVP with foreseeable effort and costs. If there is no concept yet one would typically start with a workshop to get the requirements and to create a concrete offer.
Besides the earnings it is important for the customer to get an overview of the costs.
- What will the production of the MVP and the full product cost?
- What are the internal costs for production and having the product (dedicated man power).
- What are the yearly costs for running the software?
As a salesperson it is important to not make any false promises. The best way is to show that the salesperson is aware of the customer's needs and that Marcel's company is fully capable of providing the answers by experts on a professional level.
The business view of the customer is only documented in this paragraph. However there should always be a documentation it is useful for a salesperson to have this information in mind and in a system. For Marcel's company HubSpot would be the best choide.
For the financial success of the project and the customer realationship in general it is important for the Salesperson to ensure that the project team of Marcel's company knows everything what was promised to the customer and that especially all documented promises are known and passed to the project before the project starts. Since Marcel is not experienced in providing IT systems when it comes to estimations and planning it is mandatory to pass these tasks to experts. There is a chance an expert is providing an estimation who will not be part of the project team. In such cases organizing an exchange between the expert and the project team is very helpful. There is always a struggle between making a realistic and attractive price to get the job and to ensure that the project is profitable and healthy for the customer relationship and further potential projects.
Marcel's company uses Scrum as a project management framework. In a typical project Marcel's company can but not always provides a Scrum Master (who his not the leader but an enabler of the project). The role of Product Owner should be taken by the customer. If the customer does not have the resources or the knowledge to take this role Marcel's company can provide a Product Owner.
Typical questions and topics
- How to manage and plan the project?
- How can the customer have an overview on the project?
- Besides the functional progress also the financial state is important.
- On larger projects having a steering committee (incl. both management representatives)
- At some customers it is not unusual to have a longer conceptional phase before the project starts.
- Does the customer needs training (Scrum Master, Product Owner)?
Usually the state of the project is documented in a system like Jira or GitHub. There also a fincial overview provided to the customer and for Marcel's company's internal controlling. Employee's of Marcel's company also document their times in an ERP which is also used for internal controlling and invoicing.
In the majority of projects Marcel's company is involved in the work of the "design team" plays a significant part. Almost any project leads to creating a software product which will be used by at least one and more often different types of end users. The design team's job is to identify the needs and requirements of the end users and ensure to have these reflected in the product by working close with rest of the team. A typical way to gather the necessary informtion is conduct interactive workshops with the customer and sometimes with the customer's end users. Designers also need to understand the business case and how this needs to be reflected in the product. Designing UI interfaces is only a small part of the job. A furhter misconception is that UI design means to create a nice looking UI. The main goal is to create a UI which fits the needs of the end users and the business case. This could also mean to have some part of the product very "attracting" to end users and a different part very concise and rational to be very efficient to work with for administrative users. For a sales person it is relevant to know that the design team's work is in the best interest of the customer. At some rather IT-illiterate customers there is challenge of convincing.
Typical questions and topics
- How to "catch" the user?
- How do we get feedback from the customer and the customer's users?
- Where and how do we document?
- What kind of different user groups do we have?
- How can we design the product (especially the UI) to achieve which goals (e.g., a hip/conservative impression?)
- How can we assess the quality of the design?
- How do the designers interact with development?
Typical tools to document the design and conception are Figma and Miro. Though for a lack of time in this example project there is no design and conception documentation. For the example project it would be a very challenging task to ensure how the quiz game could stand out from other quiz games to actually attract a significant user base.
More and more projects in Marcel's company have a data and AI aspect. When it comes to "data" a project's goal could be to provide a better view on existing data to accelerate business processes (think of a company wide knowledge base). A project's goal can also be to create or to extend data, produce new data or include all of these aspects. There are a lot of tools to gather and shape data. Especially when it comes to large amounts of data the cloud provides the space and processing power.
"AI" is a very broad term. Due to the success of the "ChatGPT" app there is the misconception that there is this one "magic AI" which can solve any problem. Even worse there are some customer requirements which solely consists of "use AI" without a business case or a clear goal. Behind "ChatGPT" there are very capable and complex AI models which can be of very good use (e.g., text generation). In other areas like having an AI model to anaylyze machine sensor data to identify potential failures a custom AI model is mandatory which creating needs different skills than interacting with an existing model (like the models behind "ChatGPT", respectively the company of OpenAI).
Typical questions and topics:
- What kind of data do we need?
- Where do we get it from?
- How can we move the source data into what we want?
- What kind of (user) data/insights do we want?
- Can we create or reuse data?
- Where can AI help us?
- What is the business case?
Creating text and images with AI is manifasted in this very repository. To existing AI models (GPT-4 and Stable Diffusion) are used. Also python is used to transfer the generated data into a format which can be imported into a neo4j database. A neo4j database is used to serve the generated data (e.g., quiz questions) to the backend and later to the frontend. Also data is gathered from the frontend (e.g., reaction time for answering a question) and stored in the neo4j database for later analysis. Such data could be used to identify the quality of the generated questions and images. As an example, if there is one question which is always answered correctly but the usere takes a long time with answering the question it could be an indicator that the question is easy but not clear enough. The database is provisioning and the actual data import is manifested in the database repository.
The software engineering part is usually the largest part of a software project since whatever the project's goal is it is usually manifested in software. It turned out that creating software in different components is the most efficient way (instead of heaving everythin in a huge monolith).
Depending on the size of the project and it also makes sense to provide the software in smaller parts than frontend and backend. This smaller parts can be developed and run independently. This allows to reduce runtime costs. For example a part that sometimes needs very extensive resource can be separated from the rest of the system. This way, way in comes to providing more computing resources only this part needs to be scaled. The rest of the system can run on smaller resources. Such parts usually come as "containers" which also helps security and to reduce complexity in the development process. When it comes to frontend and backend the frontend contains the user interface and ideally lesser logic. The backend contains the main logic and the connections to other systems (e.g., databases). The connection between frontend and backend is usually done via an API.There are large project which do not provide a frontend. Especially in such cases the backend is separated in further components (e.g., an API component and one more business logic component).
The descision which about parts are separated and how they are separated is usually made by the Software Architects. They also guide and support the rest of software engineers when it comes to technology descisions. Depending on the programming languages different tools and frameworks are used. A software architects job is also to take care about general aspects like security, performance and to ensure that the software is maintainable and extendable. He should also ensure that the software is tested and that the quality is ensured.
Typical questions and topics:
- What kind of technologies are used and what's the impact?
- What kind of people do we have (with the customer)?
- Do we need trainings or reviews?
- Do we work cross-cutting/fullstack?
- Which components do we want and what is the impact?
- How can we develop independently from each other a big system?
- What can we automize?
- How can we ensure "code quality"?
- Where can we use AI (for automization)?
- Data safety and protection?
The software engineering part (code and documenatation) is manifested in Git repositories. For this example project everthying is in the corresponding and often mentioned GitHub repositories. Some customers have other systems for documentation and code management. For example Jira, Confluence and Bitbucket.
DevOps is in the sense of a software project of Marcel's company evertyhing which is needed to get the software running as a cloud-native application from the development to the production. There are different interpretations what DevOps is. For some (customers) DevOps means more Ops (Operations) and for others practically any of the developers in the project should/could act as a DevOps engineer. In Marcel's company 'DevOps' is provided by a dedicated "DevOps Engineer" role. The role is performed by a person with strong knowledge in software engineering and modern cloud technologies. Main tasks are providing the cloud infrastructure, the CI/CD pipeline and the monitoring and logging.
Typical questions:
- Where will it run (Cloud? Which cloud)?
- How can we integrate the development with the shipping (CI/CD, GitOps)?
- If we run in the cloud how can we check the costs?
- Can wie optimize costs (FinOps)?
- How can we monitor and log the system?
In this example project the DevOps part is provided by GitHub Actions, Docker, Docker Compose and the documentation for running the project locally and in the cloud with Azure Container Apps.
For Marcel's company "Managed Services" is a service which is provided to the customer after the project is finished and can include to complete operation of the system in production. Heavily assisted with automation Marcel's will monitor the system and depending on the contract guarantees reaction times and availability. They can provide a hotline and a ticket system. The employees taking over the a managed service are usually also included in the project team. The team can also provide bug fixes and small changes depending on the contract.
Marcel's company usually does not provide managed services of an unkown system. But if the customer wants to have a managed service for a system not provided by Marcel's company there is always a questionaire avaible that can be provided.
For Marcel as a salesperson a managed service part can be a significant part of project's budget. It can also help to convince the customer to choose Marcel's company for the project since the customer can be sure that the system will be taken care of after the project is finished.
Regardless of the project's origin the following questions are relevant:
- What is the expected readiness?
- How much personal and technical attention do we need to manage the system?
- What about small developments and changes?
- Do we and the customer know the contacts?
There is no managed service provided for this example project other than the documentation of how to run the project with Azure Container Apps.
The artifacts of the following areas are not yet part of the project:
- No project planning related artifects
- No project management related artifects
- No design and conception related artifects
- No Security
- No Personalization
- No Internationalization (i18n)
- No Native Mobile App
- No General Architecture documents.
- No unit, integration or end-to-end tests
- No 100% clean separation of concerns (e.g., this repo contains the AI generator script)
Since the "how to get things running" is well documented, Marcel can experiment with aspects of the project on his on machine (e.g., modifying the AI-generated content generation).
Please follow the local setup guide to install the tools needed for running the example project locally on a Windows machine.