A cloud project is easier to hand over when the next person can understand what exists, reproduce the important checks and stop spending money on resources they no longer need. A screenshot of a successful deployment cannot answer all of those questions. Your README can.

This guide uses an illustrative learning project: a small web application running in a learner's cloud account. It is not a description of a client system or a Simply2Cloud assignment. Adapt the headings to your actual build. Do not create paid resources just to complete the document.

Start with purpose and current state

Describe the task your project solves in plain language. Say who uses it, what input it accepts and what output it produces. Explain whether the deployment is currently available, paused or removed. A reader should not need to follow a broken demo link to discover that the environment was taken down.

GitHub's README guidance describes the file as a place to explain what a project does, why it is useful and how people can use it. For a cloud project, add operational context: who controls the account, which environment the instructions concern and when you last checked them. Keep account identifiers private where they are not needed.

For the example application, an opening might say: “A practice web service for submitting fictional support requests. The demonstration environment has been removed; the repository contains configuration and recorded test results.” That is clearer than claiming a service is production ready because it once loaded in a browser.

Show the boundaries of the system

Include a small architecture diagram or a written request flow. Identify the entry point, application, data store and supporting components you actually used. Explain where authentication happens and which component can communicate with which other component. Label planned additions separately from implemented ones.

Do not decorate the diagram with services absent from your configuration. If a database runs on the same machine as the application, show that and explain the limitation. If you have no redundancy, state that plainly. The purpose is to make design choices inspectable, not to make a learning exercise resemble a larger commercial system.

List prerequisites before instructions

Name the tools, versions, account permissions and local setup your tested process requires. Separate what a reader must install from optional conveniences. Link to the relevant vendor documentation for installation, because supported versions and setup steps can change.

Use placeholders for configuration values and explain where authorised users obtain them. Never place passwords, access tokens, private keys or real customer data in the README, screenshots or example files. A configuration template should identify the required setting without supplying a working credential.

Explain deployment and removal together

Put your tested deployment procedure next to its intended environment and expected result. Describe the action before the command: which resources will be created, what access is needed and how a reader can tell the operation completed. Include commands only after testing them against the stated configuration.

Cloud resources may incur charges. Explain which components in your project can create costs, link to current provider pricing and identify how to check the account's billing view. Do not describe a project as free simply because a particular learner received a credit or trial offer.

Document teardown as carefully as setup. Specify the environment the cleanup affects, anything that must be retained, and how you check for remaining resources afterwards. A removed application does not necessarily mean every associated storage, backup or networking resource has been removed. Check your actual inventory rather than treating an empty browser page as proof.

Record tests that another person can repeat

A useful test record connects an action to an observation. For this illustrative application, suitable headings could be:

  • Test case and purpose.
  • Preconditions and environment.
  • Action performed.
  • Expected result.
  • Actual result and evidence location.
  • Date checked and unresolved limitations.

Record both ordinary use and a controlled failure. For example, explain how you checked that the application reports an unavailable dependency without exposing internal configuration. Do not deliberately disrupt a shared or production environment. Use an authorised practice setup and describe its boundaries.

A statement such as “tested successfully” is hard to assess. A record that identifies the request, expected response and observed result lets another learner repeat the check or challenge your conclusion.

Make troubleshooting a short decision path

Start with symptoms a reader can recognise. If the application cannot be reached, identify the checks relevant to your design: resource state, the configured endpoint and the application's own logs. Explain what evidence each check supplies. Avoid offering a generic command collection without showing which problem each command investigates.

Keep destructive recovery actions out of the first response. A restart can erase useful evidence or temporarily hide a recurring issue. Document what to inspect first, when intervention is appropriate and what to verify afterwards. Never recommend weakening access controls simply to make a test appear to pass.

Give the next maintainer a clear handover

List known limitations, unfinished work and decisions that need revisiting. Explain what you would change for a different workload without claiming you have already implemented it. Link longer procedures from the README so the overview remains readable.

Include an ownership note for shared projects. Identify which parts you created, what was supplied and which materials may be shared. A practice deployment, a selected project opportunity and a client assignment are different things. Your documentation should describe the work you actually completed.

Common questions

Does the demo have to stay online?

No. Explain that it is offline and preserve appropriate configuration, test evidence and screenshots. Keeping paid infrastructure running solely for a portfolio may be unnecessary. Someone should still be able to understand your design and the limits of the evidence.

Should every command be in the README?

Keep the essential setup, verification and cleanup path easy to find. Put longer procedures in linked documents. Check that the links work and that the instructions agree with the current configuration rather than an earlier version of the project.

Can AI write the documentation?

It can help organise notes, but it cannot establish that your deployment worked. Compare every generated instruction with your own configuration and test record. Remove invented commands, resources and results. Read the document as if you had never seen the project before.

Bring your README and one concrete question to a Simply2Cloud counselling session. You can also explore the Cloud Project Lab to understand how course practice and selection for further work differ.

Source: GitHub Docs: About READMEs. The cloud handover exercise and checklist are editorial recommendations, not a vendor certification standard.