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)? > >My preferences would be > > 1. Sentence case > 2. Sentence case > 3. Underscores > 4. Declarative > >but I am the new kid on the block. > >Whatever is the Royale way for these matters, I want to declare it in the >README for the doc project so other contributors have four fewer things to >stall over > >a > >-- >Andrew Wetmore > >https://na01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fcottage14. >blogspot.com%2F&data=02%7C01%7Caharui%40adobe.com%7Cb24a282adf9b448995cd08 >d5633ff1cd%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C636524048646177645 >&sdata=nhqu4NYTGm7xmMiAuKP2FTP6mtTK97iz8RPcWrrjbQg%3D&reserved=0
