Hi Andrew, Thanks for doing the research. I didn't even think about "-". That seems like a good idea to me.
I think of page titles and TOC entries as chapter titles in books so my first instinct is to use title case, but if you really want to use sentence case, that's fine with me. I feel the same way about section headers in the content as well, but either way is fine. If you want to do a massive scrub of the develop branch, go ahead and do it and let us know when you are done. I will go play around with the ASDoc app today so I don't get in your way. Reminder: use "git mv" or its equivalent when renaming files. I've seen Git seem to lose track if I just rename via the file system. Thanks, -Alex On 1/24/18, 9:44 AM, "Andrew Wetmore" <[email protected]> wrote: > 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://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fpractisin >c.com%2Fblog%2Fmedical-website-design%2Ftech-tip-month-naming-files-proper >ly-better-accessibility-usability%2F&data=02%7C01%7Caharui%40adobe.com%7Cd >3caeddc00764bba1f3008d563521c87%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0 >%7C636524126676229651&sdata=uuIpSctA8dw3YI0PTKpI6hjOSk5%2FMHYzZ4HNqxR66kg% >3D&reserved=0 >[2] >https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.hurid >ocs.org%2F2016%2F07%2Ffile-naming-conventions-why-you-want-them-and-how-to >-create-them%2F&data=02%7C01%7Caharui%40adobe.com%7Cd3caeddc00764bba1f3008 >d563521c87%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C636524126676229651 >&sdata=RwSEoJ4XrC3BxcvHudAEYJKewEkUSZLQtkoizhLbWfE%3D&reserved=0 >[3] >https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fusability >geek.com%2F12-effective-guidelines-for-breadcrumb-usability-and-seo%2F&dat >a=02%7C01%7Caharui%40adobe.com%7Cd3caeddc00764bba1f3008d563521c87%7Cfa7b1b >5a7b34438794aed2c178decee1%7C0%7C0%7C636524126676229651&sdata=MAZ0mKHOoqFd >sdDp5xzVfl4gF1z5mUBoHo11dtmIDHI%3D&reserved=0 >[4] >https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.winth >rop.edu%2Fweb%2Ffilenaming%2F&data=02%7C01%7Caharui%40adobe.com%7Cd3caeddc >00764bba1f3008d563521c87%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C6365 >24126676229651&sdata=tqAFNsAr6m6jDFih9sQr1vuSx1DkBNaUhZ%2FEFrNSDJM%3D&rese >rved=0 >[5] >https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.thesi >tewizard.com%2Fwebdesign%2Fcreate-good-filenames.shtml&data=02%7C01%7Cahar >ui%40adobe.com%7Cd3caeddc00764bba1f3008d563521c87%7Cfa7b1b5a7b34438794aed2 >c178decee1%7C0%7C0%7C636524126676229651&sdata=5G2s8qQ8bipZOfdGNvk3UCgOnY7a >gfo07acJJz4oWGU%3D&reserved=0 > >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 > >https://na01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fcottage14. >blogspot.com%2F&data=02%7C01%7Caharui%40adobe.com%7Cd3caeddc00764bba1f3008 >d563521c87%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C636524126676229651 >&sdata=84D2EEs4WBlICIOJ%2F0fwqOa%2BtPpHQwNXxiPPt2ju1Rg%3D&reserved=0
