How to submit content
The content on this site is a team effort and it's open to any contributions. The following information outlines how to prepare your content and assets for submission.
You should always request a review from another member of the team before publishing.
Writing clear docs
- Keep content simple – don’t attempt to flex your knowledge and don’t assume your reader is an expert
- State clearly who the intended audience is
- Open with a clear paragraph stating the document's purpose (for example, what do you hope to assist or inform with)
- If it fits with the document, use key points under the opening paragraph to highlight the key topics
- Keep titles short
- Content should be be culturally neutral (for example, don’t use 'piece of cake' or 'Bob’s your uncle'
- Any samples provided, particularly code, should be functional and match our standards
- Use consistent terminology for the same things (an example of this is the glossary for component documentation)
- When working with illustrations, example graphics or diagrams, don’t put more than one paragraph or subject's worth of information into the visual, and add a caption to explain what it represents
- When we’re linking off to a page or document, we should use clear, descriptive language and provide more information on where the link will take the user
Style guide
- Use capital letters when indicating the name of a component (for example, Icon Button)
- Keep paragraphs short and sweet – break up items into bullet points if it's more concise
- Use images where appropriate to support written content (images should have example content, not Lorem Ipsum)
- Link to other docs or components if they're referenced
- Documentation should be in the active voice, as it keeps sentence short and straight to the point (for example, 'the player kicks the ball', not 'the ball is kicked by the player'
Image assets
- The max width of images should be 750px (height will scale proportionally)
- Use components where possible so that the inherit and updates into the documentation
- Use the Figma Frame block in Supernova to add the appropriate frame to the page
- Video URLs should be supplied as embed URLs, and files should be accessible by any member of Phoenix Group
- Other file assets such as PDFs and Microsoft docs can be attached (please make sure these are accessible by members of Phoenix Group)
Hiding pages
While you work on pages you may want them to be hidden from published content.
You can hide your page from being published using an underscore ('_') before the page name. You can also share the page by creating a preview URL
https://compound.supernova-docs.io/compound/latest/<section>/<group>/<page>/<page>.html
Although it looks complicated, the structure can be created by looking for a page in a section and just changing the last part.
For example, to add a date picker to the Standard Life components, title the page '_Date Picker' in the admin area, then copy another component URL and change it to:
https://compound.supernova-docs.io/compound/latest/standard-life/foundations/components/date-picker.html
Reviews and publishing
Supernova allows the editor to create a draft of content. This can be shared to team members for review. Be aware, this will create a preview of all content that has been drafted, even by other members of the team.
Just like our Figma components, all content should have a review from at least two other members of the team.
Supernova has the ability to save draft content. Share the draft content with the two reviewers so that edits and feedback can be made.
When those reviews have been completed, you can publish the documentation to live.
Writing tools
When you're writing a document, you can always use our UX writing guide or copy style guide for help and support.
The following tools can also help you when you're writing content:
- Hemingway App - Inline audit of your writing readability
- Grammarly - Desktop app or browser extension to proof your work in real time