Maylancer Docs Writing

Maylancer Documentation Writing Style

How to write package and library documentation in the Maylancer house voice. This governs writing and structure only, not coding conventions. Apply it to web package docs, README files, API references, and any prose that has to sound authored by one voice across a whole docs site.

1. Page Anatomy (fixed skeleton)

Every intro page follows this order top to bottom:

1. H1 — package name. Plain, no tagline baked in. ("Laravel Permission", "Media Library", "Browsershot")
2. One-line purpose statement. What the package does in under ~10 words, phrased as a capability not a feature list. ("Associate users with roles and permissions", "Render web pages to an image or PDF")
3. ## Introduction — 2 to 4 sentences. What the package is, sometimes the problem it solves. This is the only place marketing-adjacent language shows up.
4. ### On this page — anchor-link list of every subsection. Pure navigation, no prose. Long pages only.
5. Body sections (##/###) — one concept per section, ordered the way a reader needs them: basic capability → more capability → configuration → edge cases. Sections are NOT numbered. Order does the sequencing.

Skip any company-services or "hire us" brand block. That is a business layer, not a documentation technique. Do not replicate it unless the task is explicitly a company doc site with a services upsell.

Inner and deeper pages (basic-usage, advanced-usage, installation) drop the intro layer entirely. Open directly with the first concept heading. No re-introduction, no restated purpose. The reader already read the intro.

2. The One Rule That Never Breaks: Code Needs a Lead Sentence

Every code block gets exactly one sentence directly before it, and that sentence ends in a colon. Never a bare code block. Never more than one paragraph of setup before it.

Two flavors, chosen by page depth:

Flavor A — casual invite (intro pages). Demos a capability, low stakes, inviting.

"Here's a quick example:" "Once installed you can do stuff like this:"

Flavor B — declarative requirement (inner/reference pages). States a fact or requirement. No invitation, no question.

"A Role and a Permission are regular Eloquent models. They require a name and can be created like this:" "To associate media with a model, the model must implement the following interface and trait:"

Never mix flavors on the same page tier. Intro pages may use a rhetorical question before Flavor A ("Want to store large files on another filesystem? No problem:"). Inner pages never ask a question before code. They are pure declaration.

3. Sentence Rhythm

Short declarative sentences alternate with medium explanatory ones. Nothing past roughly 25 words. No compound sentences stacked with multiple subordinate clauses. State the fact, then unpack it in the next sentence. One sentence never tries to do both.

"This package can associate all sorts of files with Eloquent models." "It provides a simple, fluent API to work with."

The workhorse opener for a section or a page is "This package [verb]s..." — allows, provides, offers, adds, can, contains. Nearly every intro paragraph opens this way or within the first two sentences.

4. Tone Splits by Depth (two registers, one voice)

The finding most likely to get missed. "Casual" does not apply everywhere.

Intro / marketing-adjacent pages:

• Contractions used freely: "here's," "you've," "we've got you covered"
• Occasional rhetorical question plus reassurance: "Want to X? No problem:"
• Light personality allowed. No emoji as a norm.
• Second person throughout: "your model," "you can"

Inner / reference / usage pages:

• Zero contractions. Full forms only: "will," "does not," "cannot."
• No rhetorical questions. Pure declaration.
• Imperative voice for instructions: "Add the trait," "Create a permission," "Use save."
• Still second person where relevant, but the chatty asides disappear.
• Professional, direct, instructional. No hedging. "might," "perhaps," "you may want to consider" do not appear.

Same vocabulary discipline (short sentences, no filler), different warmth. The split is set by how deep the reader is, not by topic.

5. Recurring Phrase Bank

Pull from these instead of inventing new connective tissue. Consistency across pages is what makes the site feel like one author:

• "This package [allows you to / provides / offers / can / contains]..." — default opener
• "Here's a quick example:" / "Here's how you can use it:" — code lead-in, casual register
• "You can install the package via composer:" — fixed installation phrasing, always this exact structure
• "You can optionally publish the config file with:" — fixed optional-step phrasing. Optionality is always stated with "optionally," never implied
• "Read more about it in the [X] documentation." / "Read the full story in [X]." — cross-reference, always a direct link, never "see below"
• "If you're using [edge case], then [requirement]." — conditional caveat (see §6)
• "Out of the box..." / "Once installed..." — capability-is-already-there framing
• "On this page" — fixed heading for the anchor-link TOC, verbatim every time

6. Caveats and Edge Cases

No warning boxes, no "Note:" callouts, no admonition blocks. Every caveat is two sentences:

1. A conditional clause naming the edge case.
2. The requirement or consequence, followed immediately by a link to the page that covers it in depth.

"If you're using multiple guards then the guard_name attribute must be set as well. Read about it in the using multiple guards documentation."

That is the whole pattern. No bold "Warning," no icon. The caveat is a sentence, placed where it is relevant, with an escape-hatch link. It keeps the main page uncluttered and pushes depth to a dedicated page.

7. Installation Section (fixed template)

## Installation

You can install the package via composer:

```bash
composer require maylancer/package-name

You can optionally publish the config file with:

php artisan vendor:publish --tag="package-name-config"

This is the contents of the published config file:

// config contents

Required steps state the action plainly ("You can install... via composer"). Optional steps are flagged with the word "optionally." That single word is the entire mechanism separating must-do from may-do. No separate "Required" / "Optional" labels.

## 8. Why vs. How

Inner pages almost never explain *why* a feature exists. They assume the reader arrived with intent and show *how* immediately. Intro pages front-load *why* one of two ways:

- **Problem-then-solution in one line:** "Rename a post and its URL changes with it. Every bookmark and shared link now returns a 404. Enable `selfHealing`..." The cost of not having the feature is stated before the feature.
- **A short "why would you use this" bullet list** before any code, for packages where the value is not obvious from the name.

When the name plus one-line subtitle already makes the value obvious, skip the *why* entirely and go straight from subtitle to first code example.

## 9. Lists vs. Prose

- **Bullets:** navigation, feature enumeration, prerequisite lists, contrast pairs.
- **Prose:** all conceptual explanation, all requirement statements, all lead-ins to code.
- **Numbered lists:** essentially absent. Sequential processes are conveyed by heading order. A reader moving top to bottom through the sections is the "numbering." Headings carry the sequence, prose stays flowing.

## 10. Explicitly Avoided

None of these appear:
- Transition words: "furthermore," "moreover," "additionally," "in conclusion," "that said"
- Admonition boxes ("Warning," "Tip," "Note")
- Hedging: "might," "could potentially," "you may want to consider"
- Passive voice as the default. Active voice dominates: "the package registers..." not "the service provider is registered by..."
- Marketing superlatives without backing: "the best," "revolutionary," "game-changing." Claims are made through capability statements, not adjectives.
- Long compound / subordinate-clause sentences

## 11. Reusable Page Skeleton

```markdown
# [Package Name]

## [One-line capability statement, under 10 words]

## Introduction

[2-4 sentences. "This package [verb]s..." opener. State what it does.
Optionally one line on the problem it solves, or a short "why use this"
bullet list if the value is not obvious from the name.]

### On this page

- [Section 1]
- [Section 2]
- [Section 3]

## [First capability, as a heading]

[1-2 declarative sentences. Casual lead-in on an intro page ("Here's a quick example:"),
declarative requirement on a deeper page ("To do X, you must Y:").]

```[language]
[code example]

[Optional: one sentence unpacking what just happened. No question, just the fact.]

[Second capability, as a heading]

[same pattern]

Installation

You can install the package via composer:

composer require [vendor]/[package]

You can optionally publish the config file with:

php artisan vendor:publish --tag="[package]-config"

## 12. Worked Before/After

**Generic AI-flavored paragraph (avoid):**
> "In order to leverage the full capabilities of this package, it is important to first understand the underlying architecture. This package provides a comprehensive suite of tools that enable developers to seamlessly integrate various functionalities into their applications, thereby enhancing overall productivity and efficiency."

**House-style rewrite:**
> "This package gives your models a fluent API for handling permissions. Once installed, you can assign roles and permissions with a single method call:"
> `[code block]`

The rewrite cut the throat-clearing, dropped the abstract nouns ("capabilities," "functionalities," "efficiency"), stated the mechanism plainly, and reached the code in two sentences instead of one long one.

---

**Scope:** this skill covers writing and structuring style only, not coding conventions. Those live in the separate `maylancer-laravel-php`, `maylancer-javascript`, `maylancer-security`, and `maylancer-version-control` skills.