Documenting a new project¶
Presenter¶
Special thanks¶
This presentation was developed with valuable input and feedback from:
A new project can either be an existing project you are new to or a new project still in its early stages of development. Most of the time, you will work on existing projects since it’s rare to find a project without features, codebases, READMEs, or design documents.
General principles to keep in mind¶
Regardless of whether you join an existing project or help build one from scratch, certain principles can guide your documentation work from day one. Following them early helps you work efficiently, avoid friction, and maintain scalable documentation.
Keep everything simple¶
It’s important to keep everything simple at the start. Your processes, technologies, and workflows should be as seamless as possible. This is because any wrong style choices, incorrect technology, or cumbersome information architecture may cause problems later.
Avoid excessive advanced planning. You don’t need to write a complex style guide or create grand website architecture plans. This takes too much time away from immediate needs.
Eliminate writing styles, markup formats, and technical decisions that make you dread creating content. Remove fragile structures that break with every change and avoid processes that require excessive effort to build or deploy. Tackle anything that costs too much to maintain before it consumes your time and energy.
Also, you don’t need to create much content early on. It’s natural for your documentation to develop in small increments, similar to your codebase or knowledge base.
Address loose ends early¶
Any growth in the project will amplify even the smallest issues, so take action to address them early. If your drafting, editing, and writing processes make your work difficult, reconsider them. Additionally, only maintain processes and tools that can scale.
You must keep track of any issues or tasks that people raise. People often drop links, messages, or notes on wikis to notify you, and this information accumulates quickly. So you must build a reliable and robust pipeline to address your backlog using the task management tool of your choice.
Also, consider how easily you can reverse decisions. For example, anchoring references to specific documents instead of using relative links may create problems later. This is because restructuring the website would require manual link updates or complex regular expressions.
You shouldn’t have more documentation than your project requires. If the project is still in its early stages, extensive guides or a comprehensive knowledge base are unnecessary. Instead, focus on creating a core set of documentation that you can expand later.
Identify stakeholders and audience needs¶
Successful documentation projects start with a clear understanding of the people involved. Identify stakeholders, learn their wants and needs, and define measurable quality criteria. Establish clear points of contact and set ultimate goals for the documentation, such as whether it serves as a reference, a sales tool, or another purpose. This early clarity shapes decisions and provides a consistent basis for reviews and quality assessments.
Also, understand the audience by identifying their wants, needs, and expectations. Create personas and use them to guide every content and design decision.
Keep feedback manageable by limiting contact channels, possibly to a single ticketing system. This preserves mental bandwidth and creates a process that produces consistent, high-quality results.
Create concept and content maps¶
Map out your project before writing. The concept map organises knowledge, while the content map tracks tangible materials.
Create a concept map that lists every concept, item, artifact, and topic your documentation must address. Show how these elements relate to each other, and maintain this map as a living reference. It will guide your discussions with developers and stakeholders, and ensure nothing important gets overlooked.
Alongside the concept map, create a content map, which is an inventory of all existing documentation artifacts. Note where each artifact lives, how to work with it, and how to manage it.
Do thorough prior research. Examine competitors and similar projects to see how they solve documentation problems. Study their methods, identify what fits your context, and adapt those approaches with improvements.
Become a power user of your product¶
Aim to become a power user for your project and maintain hands-on experience. Develop self-reliance as early as possible so you can answer your questions without relying on subject matter experts.
Read the code whenever possible, as it remains the ultimate source of truth. If you can’t read it yet, invest time in learning it. You should approach every opportunity to speak with developers or stakeholders while fully prepared, so that the conversation yields intended results. Remember that you shouldn’t expect anyone to explain everything to you.
Start with minimum viable documentation¶
When starting a new documentation project, define a clear goal and translate it into concrete tasks. Complete each task to the best of your ability, then review the results with a trusted reviewer, apply necessary corrections, and refine your approach for the next cycle. Repeat this cycle until the work meets your standards.
You can start by describing what already exists and prioritising your content map. Break it into clear sections so you can track coverage easily. Start with a Minimum Viable Product (MVP), such as a concise one-pager, and expand later. Write what you know now and address remaining gaps as you progress.
Operate from a clear content map to navigate unfamiliar territory and guide discussions, planning, and writing. Start by publishing what you already know, then use future updates to expand coverage. Alternate between writing and refactoring in distinct phases to preserve focus and maintain quality.