From a quick and non-comprehensive review:
- Practis [1] recommends using all lower case, with no spaces, for file
names, with _ or - to join words and no other punctuation.
- Huridocs [2] concurs and suggests some tools for doing bulk file
renaming.
- Winthrop University[4] recommends - instead of _ for joining words in
file names because it improves SEO. Website argues against both _ and %20
because they can be misread by search engines and humans.
- The Site Wizard [5] pushes hard for all lower case, no special
characters, no running words together, and - instead of _ between words.
Nobody out there seems to care about imperative ("Get Started") versus
gerund ("Getting Started"). I will note that, over the course of a large
ToC such as ours, going with imperative will save us maybe 100s of
characters and create a cleaner look.
Nobody seems to have strong opinions about title case (How to Do This)
versus sentence case (How to do this) for the text title within a document.
a
[1]
https://practisinc.com/blog/medical-website-design/tech-tip-month-naming-files-properly-better-accessibility-usability/
[2]
https://www.huridocs.org/2016/07/file-naming-conventions-why-you-want-them-and-how-to-create-them/
[3]
https://usabilitygeek.com/12-effective-guidelines-for-breadcrumb-usability-and-seo/
[4] https://www.winthrop.edu/web/filenaming/
[5] https://www.thesitewizard.com/webdesign/create-good-filenames.shtml
On Wed, Jan 24, 2018 at 12:19 PM, Alex Harui <[email protected]>
wrote:
> HI Andrew,
>
> Good question. I'm pretty sure I don't care as long as it meets usability
> goals. Maybe you already know what usability goals a "help docs" site
> should have, but maybe we should first agree on usability goals and work
> backwards to how the directory and file names affect that if at all. I
> didn't know how Jekyll worked when first putting together the skeleton so
> I picked spaces (%20) just as a guess.
>
> I think the usability goals are something like:
> A) what shows up as the page/tab title?
> B) What do the links look like?
> C) Do search engines care?
> D) What do the links look like in search engine results?
> E) What do the links look like when hovering over them? Or in Bookmarks?
> F) Do people have expectations around uppercase, lowercase, sentence case,
> etc?
> G) What will screen readers read to vision-impaired people?
>
> Other user-facing issues?
>
> I believe I've learned that in Jekyll the title is in the "front matter"
> and is independent of the file name. If you want to make some changes and
> test that out, feel free.
>
> I don't know if folks would rather see "_" instead of %20 in links. Or
> even Camel Case: GettingStarted.html.
>
> Thoughts?
> -Alex
>
> On 1/24/18, 7:34 AM, "Andrew Wetmore" <[email protected]> wrote:
>
> >This is for the help documentation, but maybe there are already some
> >conventions in place for the code base that we should follow.
> >
> >
> > 1. Are we using all lower case, sentence case (Getting started), or
> > initial caps (Getting Started) for directory and file names?
> > 2. Are we using sentence case or initial caps for the title at the top
> > of each help doc's text?
> > 3. Are we using underscores (Getting_Started) or HTML code
> >(Getting%20Started)?
> > I see the former in the code for the web page and the latter for the
> >help
> > docs.
> > 4. Are we using declarative verbs (Get started) or gerunds (Getting
> > started)?
>
>
--
Andrew Wetmore
http://cottage14.blogspot.com/
