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: say who your article is relevant to and why. What problem of theirs are you helping to solve? e.g. 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.
Organize your content like a building, and show us the blueprint first.
Give vectorhub editors a one-sentence-per-section outline, to show us what you want to communicate. This is a huge timesaver, and helps us make sure your article does what you want it to.
Give an overview of where you're going in your Introduction. In your article itself, 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.
Link (scroll-to-anchor) between concepts in your article (or to other articles on the platform) where it makes sense.
Use github basic formatting, rather than html.
Use simple language, short sentences, write only what's essential. 800-2500 words.
Length: Articles must be at least 800 but less than max 2500 words.
Be clear and concise. 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. Avoid superlatives.
Get the substance down first. First, complete your article in point form. Make sure you've included everything that your article needs to make sense and convey value to your readers. Don't try to be stylish - this usually obfuscates meaning.
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.
Text only goes so far. Complement your words with diagrams, graphs, charts, code snippets, equations, images and any other visual tools that explain your work more efficiently.
Write mathematical expressions using LaTex.
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."
Use consistent verb tenses.
Give credit where credit is due. Always.
Hyperlink to sources, rather than including the source url. Don't use footnote or endnotes.
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. If you're not sure whether to cite it, you probably 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. This exercise saves a lot of time and energy, and ensures your headings and subheadings are accurate.
Use a spell and grammar checker.
It's an article about tech. Use relevant, familiar technical terms.
Use technology-specific terminology. If you think the thing you're describing is unfamiliar to most readers, it probably is. Link to external resources that provide more in-depth explanations of terms you don't have space to explain in your article.
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.
Stay updated with VectorHub
Continue Reading
