On 1/24/18, 10:07 AM, "Andrew Wetmore" <[email protected]> wrote:
>My argument for sentence case over title case is that, in general, fewer >capital letters makes for easier scanning and comprehension, especially >for >folks for whom English is not the first or a comfortable language. OK, If my fifth grade teacher (that I ran into the other day) give me any grief about it, I will point him to you ;-) > >I do not have time today to scrub existing files and the table of >contents, >and I also want to give other people a chance to weigh in if they want to. >However, within a day or two let's proclaim a standard and I will help >make >what we have done so far comply with it. OK, I will continue to mess around with the TOC and Features page to verify the third-level works. FWIW, I think we could put the TOC in a .JSON file and make adding a new page as simple as editing the TOC's JSON file instead of having to make changes in about 8 places in the docpage.html. But that would take about a day so I'm not sure if it is worth it. > >You terrify me with your comments about Git. I don't even know what "git >mv" would be, although I presume it is down in command line purgatory >somewhere. You will probably have to get to know Git better. 'Git mv" is how to rename files under Git's control. Just using the file system seems to confuse it some times. Not sure if there is a way to rename using the GH UI. Thanks, -Alex > >On Wed, Jan 24, 2018 at 1:59 PM, Alex Harui <[email protected]> >wrote: > >> 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%7Cfa7b1b5a7b34438794aed2c178de >> cee1%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%7Cd3caeddc00764bba1f3008d56352 >> 1c87%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%7Cfa7b1b5a7b34438794aed2c178de >> cee1%7C0%7C0%7C6365 >> >24126676229651&sdata=tqAFNsAr6m6jDFih9sQr1vuSx1DkBN >> aUhZ%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%7Cd3caeddc00764bba1f3008d56352 >> 1c87%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%2Fcottage1 >>>4 >> . >> >blogspot.com%2F&data=02%7C01%7Caharui%40adobe.com% >> 7Cd3caeddc00764bba1f3008 >> >d563521c87%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0% >> 7C636524126676229651 >> >&sdata=84D2EEs4WBlICIOJ%2F0fwqOa%2BtPpHQwNXxiPPt2ju1Rg%3D&reserved=0 >> >> > > >-- >Andrew Wetmore > >https://na01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fcottage14. >blogspot.com%2F&data=02%7C01%7Caharui%40adobe.com%7C7317d53503af4b2c90ed08 >d563554b12%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C636524140341841645 >&sdata=%2B%2FNaXJmOZH3kCFUfxGP6%2FVKLJGd2GCiupG05%2F9Ao9xY%3D&reserved=0
