You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@royale.apache.org by Andrew Wetmore <co...@gmail.com> on 2018/01/24 15:34:07 UTC
Directory and File naming conventions
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
http://cottage14.blogspot.com/
Re: Directory and File naming conventions
Posted by Alex Harui <ah...@adobe.com.INVALID>.
The .md files get built by Jekyll on our CI server. The results end up
here:
http://apacheroyaleci.westus2.cloudapp.azure.com:8080/job/RoyaleDocs_Stagin
g/lastSuccessfulBuild/artifact/_site/
HTH,
-Alex
On 1/24/18, 2:21 PM, "carlos.rovira@gmail.com on behalf of Carlos Rovira"
<carlos.rovira@gmail.com on behalf of carlosrovira@apache.org> wrote:
>Hi, I see you work in develop thought GitHub with .md files. I can see as
>well .css with website fonts. But I don't know how to see the generated
>site.
>Can someone explain me how to see the final html content resulting from
>apply the css to the markdown files?
>
>Thanks
>
>2018-01-24 22:13 GMT+01:00 Alex Harui <ah...@adobe.com.invalid>:
>
>> OK, I'm done playing in the Welcome folder. The third-tier TOC seems to
>> be working.
>>
>> I am moving on to the CreateAnApplication folder.
>>
>> -Alex
>>
>> On 1/24/18, 12:10 PM, "Andrew Wetmore" <co...@gmail.com> wrote:
>>
>> >I should have added that I will go edit out the hyphens in the front
>> >matter.
>> >
>> >On Wed, Jan 24, 2018 at 4:09 PM, Andrew Wetmore <co...@gmail.com>
>> >wrote:
>> >
>> >> Let's give it a try.
>> >>
>> >> On Wed, Jan 24, 2018 at 4:04 PM, Alex Harui
>><ah...@adobe.com.invalid>
>> >> wrote:
>> >>
>> >>>
>> >>>
>> >>> On 1/24/18, 9:59 AM, "Alex Harui" <ah...@adobe.com.INVALID> wrote:
>> >>>
>> >>> >Hi Andrew,
>> >>> >
>> >>> >Thanks for doing the research. I didn't even think about "-".
>>That
>> >>> seems
>> >>> >like a good idea to me.
>> >>>
>> >>> Speaking of '-', I saw in your recent commit that the Front Matter
>> >>>title
>> >>> had '-' in it. That title becomes the <html><head><title> so I
>>don't
>> >>> think that should have '-' in it. I think it can use plain spaces
>>and
>> >>> doesn't need escaping. I don't think it is used to resolve links.
>> >>>
>> >>> Thoughts?
>> >>> -Alex
>> >>>
>> >>> >
>> >>>
>> >>>
>> >>
>> >>
>> >> --
>> >> Andrew Wetmore
>> >>
>> >>
>> >>https://na01.safelinks.protection.outlook.com/?url=
>> http%3A%2F%2Fcottage14
>> >>.blogspot.com%2F&data=02%7C01%7Caharui%40adobe.com%
>> 7C19666b9f52de4eed2204
>> >>08d563668a33%7Cfa7b1b5a7b34438794aed2c178de
>> cee1%7C0%7C0%7C636524214405634
>>
>>>>774&sdata=MFWkvT%2ByNTI4FToVdzn%2BdtCNqJDtkceV0cKJ8CsQXrk%3D&reserved=0
>> >>
>> >>
>> >>
>> >>
>> >>
>> >
>> >
>> >--
>> >Andrew Wetmore
>> >
>>
>>>https://na01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fcottage1
>>>4
>> .
>> >blogspot.com%2F&data=02%7C01%7Caharui%40adobe.com%
>> 7C19666b9f52de4eed220408
>> >d563668a33%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%
>> 7C636524214405634774
>> >&sdata=MFWkvT%2ByNTI4FToVdzn%2BdtCNqJDtkceV0cKJ8CsQXrk%3D&reserved=0
>>
>>
>
>
>--
>Carlos Rovira
>https://na01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fabout.me%2
>Fcarlosrovira&data=02%7C01%7Caharui%40adobe.com%7Cbfc4c02edc284144f87908d5
>6378dd76%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C636524293117331892&s
>data=uOkzT8bYhOPPp7wTFitEmsn8v2DVr3I9%2FcXsCftAru0%3D&reserved=0
Re: Directory and File naming conventions
Posted by Carlos Rovira <ca...@apache.org>.
Hi, I see you work in develop thought GitHub with .md files. I can see as
well .css with website fonts. But I don't know how to see the generated
site.
Can someone explain me how to see the final html content resulting from
apply the css to the markdown files?
Thanks
2018-01-24 22:13 GMT+01:00 Alex Harui <ah...@adobe.com.invalid>:
> OK, I'm done playing in the Welcome folder. The third-tier TOC seems to
> be working.
>
> I am moving on to the CreateAnApplication folder.
>
> -Alex
>
> On 1/24/18, 12:10 PM, "Andrew Wetmore" <co...@gmail.com> wrote:
>
> >I should have added that I will go edit out the hyphens in the front
> >matter.
> >
> >On Wed, Jan 24, 2018 at 4:09 PM, Andrew Wetmore <co...@gmail.com>
> >wrote:
> >
> >> Let's give it a try.
> >>
> >> On Wed, Jan 24, 2018 at 4:04 PM, Alex Harui <ah...@adobe.com.invalid>
> >> wrote:
> >>
> >>>
> >>>
> >>> On 1/24/18, 9:59 AM, "Alex Harui" <ah...@adobe.com.INVALID> wrote:
> >>>
> >>> >Hi Andrew,
> >>> >
> >>> >Thanks for doing the research. I didn't even think about "-". That
> >>> seems
> >>> >like a good idea to me.
> >>>
> >>> Speaking of '-', I saw in your recent commit that the Front Matter
> >>>title
> >>> had '-' in it. That title becomes the <html><head><title> so I don't
> >>> think that should have '-' in it. I think it can use plain spaces and
> >>> doesn't need escaping. I don't think it is used to resolve links.
> >>>
> >>> Thoughts?
> >>> -Alex
> >>>
> >>> >
> >>>
> >>>
> >>
> >>
> >> --
> >> Andrew Wetmore
> >>
> >>
> >>https://na01.safelinks.protection.outlook.com/?url=
> http%3A%2F%2Fcottage14
> >>.blogspot.com%2F&data=02%7C01%7Caharui%40adobe.com%
> 7C19666b9f52de4eed2204
> >>08d563668a33%7Cfa7b1b5a7b34438794aed2c178de
> cee1%7C0%7C0%7C636524214405634
> >>774&sdata=MFWkvT%2ByNTI4FToVdzn%2BdtCNqJDtkceV0cKJ8CsQXrk%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%
> 7C19666b9f52de4eed220408
> >d563668a33%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%
> 7C636524214405634774
> >&sdata=MFWkvT%2ByNTI4FToVdzn%2BdtCNqJDtkceV0cKJ8CsQXrk%3D&reserved=0
>
>
--
Carlos Rovira
http://about.me/carlosrovira
Re: Directory and File naming conventions
Posted by Alex Harui <ah...@adobe.com.INVALID>.
OK, I'm done playing in the Welcome folder. The third-tier TOC seems to
be working.
I am moving on to the CreateAnApplication folder.
-Alex
On 1/24/18, 12:10 PM, "Andrew Wetmore" <co...@gmail.com> wrote:
>I should have added that I will go edit out the hyphens in the front
>matter.
>
>On Wed, Jan 24, 2018 at 4:09 PM, Andrew Wetmore <co...@gmail.com>
>wrote:
>
>> Let's give it a try.
>>
>> On Wed, Jan 24, 2018 at 4:04 PM, Alex Harui <ah...@adobe.com.invalid>
>> wrote:
>>
>>>
>>>
>>> On 1/24/18, 9:59 AM, "Alex Harui" <ah...@adobe.com.INVALID> wrote:
>>>
>>> >Hi Andrew,
>>> >
>>> >Thanks for doing the research. I didn't even think about "-". That
>>> seems
>>> >like a good idea to me.
>>>
>>> Speaking of '-', I saw in your recent commit that the Front Matter
>>>title
>>> had '-' in it. That title becomes the <html><head><title> so I don't
>>> think that should have '-' in it. I think it can use plain spaces and
>>> doesn't need escaping. I don't think it is used to resolve links.
>>>
>>> Thoughts?
>>> -Alex
>>>
>>> >
>>>
>>>
>>
>>
>> --
>> Andrew Wetmore
>>
>>
>>https://na01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fcottage14
>>.blogspot.com%2F&data=02%7C01%7Caharui%40adobe.com%7C19666b9f52de4eed2204
>>08d563668a33%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C636524214405634
>>774&sdata=MFWkvT%2ByNTI4FToVdzn%2BdtCNqJDtkceV0cKJ8CsQXrk%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%7C19666b9f52de4eed220408
>d563668a33%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C636524214405634774
>&sdata=MFWkvT%2ByNTI4FToVdzn%2BdtCNqJDtkceV0cKJ8CsQXrk%3D&reserved=0
Re: Directory and File naming conventions
Posted by Andrew Wetmore <co...@gmail.com>.
I should have added that I will go edit out the hyphens in the front matter.
On Wed, Jan 24, 2018 at 4:09 PM, Andrew Wetmore <co...@gmail.com> wrote:
> Let's give it a try.
>
> On Wed, Jan 24, 2018 at 4:04 PM, Alex Harui <ah...@adobe.com.invalid>
> wrote:
>
>>
>>
>> On 1/24/18, 9:59 AM, "Alex Harui" <ah...@adobe.com.INVALID> wrote:
>>
>> >Hi Andrew,
>> >
>> >Thanks for doing the research. I didn't even think about "-". That
>> seems
>> >like a good idea to me.
>>
>> Speaking of '-', I saw in your recent commit that the Front Matter title
>> had '-' in it. That title becomes the <html><head><title> so I don't
>> think that should have '-' in it. I think it can use plain spaces and
>> doesn't need escaping. I don't think it is used to resolve links.
>>
>> Thoughts?
>> -Alex
>>
>> >
>>
>>
>
>
> --
> Andrew Wetmore
>
> http://cottage14.blogspot.com/
>
>
>
>
>
--
Andrew Wetmore
http://cottage14.blogspot.com/
Re: Directory and File naming conventions
Posted by Andrew Wetmore <co...@gmail.com>.
Let's give it a try.
On Wed, Jan 24, 2018 at 4:04 PM, Alex Harui <ah...@adobe.com.invalid>
wrote:
>
>
> On 1/24/18, 9:59 AM, "Alex Harui" <ah...@adobe.com.INVALID> wrote:
>
> >Hi Andrew,
> >
> >Thanks for doing the research. I didn't even think about "-". That seems
> >like a good idea to me.
>
> Speaking of '-', I saw in your recent commit that the Front Matter title
> had '-' in it. That title becomes the <html><head><title> so I don't
> think that should have '-' in it. I think it can use plain spaces and
> doesn't need escaping. I don't think it is used to resolve links.
>
> Thoughts?
> -Alex
>
> >
>
>
--
Andrew Wetmore
http://cottage14.blogspot.com/
Re: Directory and File naming conventions
Posted by Alex Harui <ah...@adobe.com.INVALID>.
On 1/24/18, 9:59 AM, "Alex Harui" <ah...@adobe.com.INVALID> wrote:
>Hi Andrew,
>
>Thanks for doing the research. I didn't even think about "-". That seems
>like a good idea to me.
Speaking of '-', I saw in your recent commit that the Front Matter title
had '-' in it. That title becomes the <html><head><title> so I don't
think that should have '-' in it. I think it can use plain spaces and
doesn't need escaping. I don't think it is used to resolve links.
Thoughts?
-Alex
>
Re: Directory and File naming conventions
Posted by Alex Harui <ah...@adobe.com.INVALID>.
On 1/24/18, 10:07 AM, "Andrew Wetmore" <co...@gmail.com> 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 <ah...@adobe.com.invalid>
>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" <co...@gmail.com> 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 <ah...@adobe.com.invalid>
>> >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" <co...@gmail.com> 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
Re: Directory and File naming conventions
Posted by Andrew Wetmore <co...@gmail.com>.
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.
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.
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.
On Wed, Jan 24, 2018 at 1:59 PM, Alex Harui <ah...@adobe.com.invalid>
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" <co...@gmail.com> 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 <ah...@adobe.com.invalid>
> >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" <co...@gmail.com> 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
>
>
--
Andrew Wetmore
http://cottage14.blogspot.com/
Re: Directory and File naming conventions
Posted by Alex Harui <ah...@adobe.com.INVALID>.
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" <co...@gmail.com> 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 <ah...@adobe.com.invalid>
>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" <co...@gmail.com> 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
Re: Directory and File naming conventions
Posted by Andrew Wetmore <co...@gmail.com>.
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 <ah...@adobe.com.invalid>
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" <co...@gmail.com> 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/
Re: Directory and File naming conventions
Posted by Alex Harui <ah...@adobe.com.INVALID>.
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" <co...@gmail.com> 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