Had a feeling that would come!
I am not yet ready to propose "a draft style guide", but am conscious of a few issues which I think it is worth a kick around so that we are roughly of one mind. If this takes off it can be lifted into a different topic.
I think the style guide could usefully work in two directions
- User Guide and How to type pages
- In detail functional reference pages
For the moment I don't think we need to try to "legislate" for proper use of commas, correct capitalisation or appropriate use of numerals etc.. Those issues are second order compared to creating contant which serves the above purpose.
So for User Guide and How to type pages - a starter for possibly 5:
- The Above the Fold area should
- Unambiguously define what the page is about and redirect for (1) common misapprehensions (2) "expert" readers
- Page Structure. Ideally
- Pages should follow our normal linear reading process
- A page should contain a complete "chunk" of knowledge and not require diverting away to another page and returning
- Page Sections (clearly format defined) can if necessary start with a paragraph explaining what the section aims to do and offer a "skip link"
- Language needs to be plain and pitched at the sort of person who might try to do genealogy - an understanding of most common genealogical terms can be assumed - but that does not apply to IT terms.
- Sentences need to be short and if they are describing a process should use bullet points or numbered steps
- Most acronyms should be spelt out on first use in each page (or use something similar to the HMTL <abbr> tag)
- We need to be alert to using technical terms (page-sections?!) that may be unfamiliar or misunderstood by non-expert users. Linking to a glossary page disrupts reading and readers may not bother to go and look but struggle on not fully understanding.
- Images assist understanding and make pages more digestible.
- On a laptop images should preferably show the required detail without expansion. [What about tablets - are tablet users part of our audience? How we handle this could be platform dependent]
- Navigation - I have seen some guidelines before, I can't recall where, but I think they included points like:
- Page Navigation needs to take people quickly to the information they need; the more links the more opportunity to get lost
- Too much navigation can be a distraction.
- At the end of a page the navigation should anticipate where the reader wishes to go next; the next logical step, move to relevant part of Technical Reference, return to previous page