Member Resources Style Guide
A few guidelines to keep things smart and stylish.
For general usage questions, see the official documentation for BookStack (the software this site uses)
Global organization
This software uses a metaphorical hierarchy of Shelves -> Books -> Chapters -> Pages. To quote the official documentation:
Within a book you can directly create pages or you can first create chapters. Chapters provide an additional level of page grouping to keep pages organised but are optional. All the information you write is held within pages. Although books and chapters do not hold information they can be given a short description to assist with searching and visibility.
Once you start to stack-up books you can start to use Bookshelves to organise your Books. Bookshelves can contain multiple books and a single book could be placed on multiple Bookshelves.
As of this writing, all of Member Resources is one book. Topics that have a lot of materials assigned to them are chapters, whereas some smaller topics are individual pages outside of chapters (like this one). This can all be changed relatively easily with the sorting interface as the need arises. If a topic gets a lot more involved, it could be made into a chapter. If a chapter seems like enough of its own thing, it could become a separate book, and if we end up with a ton of books that need to be categorized themselves, we could add more shelves.
Page Organization
Headers automatically create a linked hierarchy, which can be used as a table of contents.
Use callouts to draw the eye to important information.
Info: Use this to attribute an article to a source
Success: Great for highlighting winning strategies
Warning: A mild heads up, i.e. some of the info on this page is outdated, or in the process of being cleaned up.
Danger: You can't touch this
For example, mark sensitive documents with the following:
Internal Use Only
Formatting
When copying text from an external document, strip the text colors and highlight colors. They interfere with the site theme (especially in Dark Mode).
Delete extraneous line breaks. The site already introduces a generous break between paragraphs, so additional returns add too much negative space.
Links and attachments
When a link takes you to a document, slide show or a PDF hosted elsewhere, save that item in a reasonably compatible format and upload it as an attachment. Link to the attached version.
If a link is pointing to an external website that seems ephemeral and not suited to attachment (i.e. a blog, news article or social media post), consider using the Wayback Machine at archive.org to grab a snapshot. You can link to that instead of the live page, in case it goes down or is moved in the future.
Setting links to open in a new window (via the dropdown menu in insert/edit link) is a good standard procedure. If someone is browsing around a bunch of links, it's easier to keep track of a few tabs than to follow the trail back to where they were after each digression.
Tables
With a little manual effort, tables can be adapted into normal text via indents or bullet lists, which will scale better to different devices. Tables are a problem for mobile browsers.
Compare the Member-Leader Roles Guide to the original for an example of one way to alter a table-heavy article
Reusing Page Content
Occasionally, it may make sense to replicate a page in more than one chapter. Instead of duplicating all the content, it's possible to have one page dynamically include the content of another page. The advantage is that if that content needs to be changed, you only have to change it in one place. The disadvantage is that it's a little weird and confusing. See the official documentation for the necessary steps.
Tags
Comments
If you're in the process of making changes or considering the best way to proceed, add a comment down below to share your thought process! Once the comment is no longer relevant, it can be archived (in case seeing that past thinking might be useful) or deleted (if it wouldn't make sense at all without its former context).