VectorHub is a community-driven learning hub. Our style guide aims to help you share your thinking and work. We care about grammar, but our priority is meaning. We want to generate productive conversation between community members. To this end, we've written ten "commandments" outlining some dos and don'ts. Please read them before you start writing your article.
Who are you writing for, and what problem are you solving?
Ask yourself why your article is valuable to your readers. Set the context: identify your readers explicitly - say who your article is relevant to and why. What problem of theirs are you helping to solve? Instead of this: "This latest software update is packed with helpful enhancements." Write this: "Our November 15, 2023 update lets web developers optimize projects by developing faster with simplified coding."
Front load your first paragraph with keywords.
Use simple language, short sentences, write only what's essential. 800-2500 words.
Write clearly and concisely. Aim for crisp minimalism. Use simple language wherever possible; write like you speak. Be minimal. Less is more. Use adjectives only when they add value.
In general, write short sentences.
Length: Articles must be at least 800 but less than max 2500 words.
Get the substance down first. Don't worry about making perfect sentences until after you've completed your article in point form. Fine-tuned, stylized prose can come later. First, make sure you've included everything that your article needs to make sense and convey value to your readers.
Use common abbreviations. e.g. "apps" instead of "applications" Introduce unfamiliar abbreviations. e.g. "RAG (Retrieval Augmented Generation)"
Skip periods on headings and subheadings. Only use them in paragraphs and body text. Use last (Oxford) commas for clarity. e.g. "We are programmers, data analysts, and web designers."
Don't add extra spaces anywhere. One space between sentences and words.
Save a thousand words. Use a picture. Represent your ideas visually whenever possible.
Text only goes so far. Complement your verbal descriptions with diagrams, graphs, charts, code snippets, images and any other visual tools that explain your work more efficiently.
Write how you speak. Be personal. In an active voice.
Write with a friendly tone. Call your audience "you" and yourselves "we."
Use contractions. e.g. Instead of "We are," "it is," and "they are," use "We're," "it's", and "they're."
As much as possible, use an active voice to explain events and relationships. e.g. Instead of: "Deep neural networks are used by GPT to learn contextual embeddings." Write this: "GPT uses deep neural networks to learn contextual embeddings."
Choose specific action verbs over generic ones. e.g. Instead of: "We made changes to the code to improve performance." Write this: "We optimized the code to boost performance."
Organize your content like a building, and show us the blueprint first.
Add clear headings and subheadings that give information and an overview to your readers. This will enable readers to navigate to relevant sections and search engines to scan it.
Give an overview of where you're going in your Introduction.
Link (scroll-to-anchor) between concepts in your article (or to other articles on the platform) where it makes sense.
Give credit where credit is due. Always.
Make sure you have permission to reuse any images you include in your VectorHub article. Cite your own modified versions of images owned by someone else as a "Modified version of" the original source.
Cite sources for all graphics, images, direct quotations, and others' unique or patented ideas.
You should cite visual elements (i.e., figures) as follows: [Title], [Author/Photographer/Artist], [Year], [Source]. Provide a hyperlink for the whole citation, pointing to the visual element source. e.g. Feed Recommendation Illustration, Arunesh Singh, 2023, superlinked.com.
Source citations go underneath visual elements. e.g.
Punctuate outside of links. e.g. "We explain our approach in more depth here."
Nail down your logic. Step back, outline, and revise.
As early as possible (when your article is still in point form), go through it, summarize each paragraph in one (concise) sentence. Now, put all your summary sentences together and see if they tell a story. Is there a logical flow? If not, rearrange, remove, or add content until the article makes sense. In our experience, going through this exercise saves a lot of time and energy. It's also a good way of checking whether your headings and subheadings are accurate.
Whenever possible, find an industry-specific reader.
It's an article about tech. Use relevant, familiar technical terms.
You're writing a technical article. Use technology-specific terminology. If you think the thing you're describing is unfamiliar to most readers, it probably is. Feel free to link to external resources that provide more in-depth explanations of terms you do not have space to explain in your article. In general, don't overcomplicate your text; communicate as simply and clearly as possible.
Hierarchize and tag.
Improve accessibility by creating headings and subheadings that are clear and accurately descriptive.
Include alt text for all images and graphics.
The VectorHub community is diverse. Be non-biased and gender neutral.
The VectorHub community is international and heterogeneous. Avoid words and phrases with negative connotations. Err on the side of caution - if you think a term might be offensive, don't use it.
Avoid stereotypes and biases.
Use gender neutral pronouns. e.g. Instead of he/his/him or she/hers/her, use they/them/their.