Editorial flow

Writing good docs is hard and at times time-consuming (pun intended). To make all this easier, our editors follow a lean workflow, similar to regular editorial workflows.

01 Drafting

• Focus on just getting the information in place. Just like how a painter paints big strokes first, not caring about any details.
• Be okay with mistakes in spelling, grammar, punctuation, and more. We'll fix those later.
• Speed is key at this stage. Sure, a table here and there could make the content read better, but we'll have time for that later.

02 Correctness edit

• Make sure the content is correct. Talk to the SMEs, manually test behavior if applicable.

03 Style edit

• Make sure the content is consistent with the rest of the docs. Use ´Vale´ to check for consistency issues.
• Check that your editor environment is set up right. See Editor setup.

04 Readability edit

• Does the text flow well? Too many sentences? Maybe split up into different paragraphs, bullet lists, or tables. (tables do come in the fluff edit too, but it doesn't matter where you do this particular thing)
• "How much can I remove without losing meaning?"
• "Is there a more straightforward way to explain this?"

05 Terminology edit

• Make sure you're consistent with how you name things throughout your texts. Repeating the same word for the same idea is a good practice in technical writing.
• Some terms should be replaced with popups. If you're working within VSCode and activate the workspace, terms will be recommended. Otherwise check styleguides/ebee/Terms.yml for an exhaustive list of terms with popups.

06 Fluff edit

• Replace static words, for example, Charge Controller, with <Term>.
• We use a custom component to help us keep terminology consistent and to provide automatic translations. See the terminology table for all the terms we've already added. If one's missing in your opinion, tell the head writer.

07 Translation

• Use the translation table to help with translating technical terms IF you have terms that don't have a <Term> component yet.
• Realistically, you should do this before a new public release. Remember that if a source file changes, the translation has to be re-done.

info

If a term is missing from the table, feel free to add it. The head writer will review your addition and add it to the table.

08 Final review

• Make sure everything is correct, and that the doc is ready for publishing. Do this yourself and have at least one appropriate person peer-review. Usually this is the Product Owner or another Subject Matter Expert.
• Remember that you need to review both the source language and translations this stage.

09 Ready to publish

• At this stage, both you and if deemed useful at least one PO have reviewed the content and fixed any last issues.
• The content is now ready to be published.

Sidenotes

• Consider whether content is high-touch or low-touch, meaning how often and how many people are reading the content?
• If it's high-touch, it makes sense to spend significant time on it, and make sure it's as good as possible, creating diagrams, etc.
• The tooling we use is not perfect, and it's not always easy to get the right result. If you're unsure about something, ask the head writer.
• Although our automated styleguide helps a lot, it can't be counted on to catch everything. The microdecisions are up to you.