potiuk commented on PR #36969: URL: https://github.com/apache/airflow/pull/36969#issuecomment-1907851710
> @potiuk I started looking at it too, will complete by EOD, but I am not very much in favour of labelling the docs as -title.rst, when only title.rst would be enough, any specific reason for the same? Yes. The main reason is that when you go to the directory or locally when you check out the files in your IDE, the 01_, 02_ prefixes make them show in the order they are also listed in the index (i.e. in **logical** order which reflects the sequence in which people should get familiar with the subject). Sort of like numbering chapters in a book. If you do not have the numbers (or otherwise consistent sorting order) when you have more than few files in a directory, when you look at it and want to find where you should edit some changes, it makes it rather difficult to find out the file you are looking for. when they are numbered and in a consistent order, it's far easier for anyone who wants to contrbute to the docs. On the other hand for the users, the prefixes in the names of files eventually do not make it any more difficult. You usually get to the right file from the index or by searching some phrases or because some other place (error message, or comment in another part of documentation) sent you there by a link. And you don't even realise you have the prefix in the link you just click and follow it. So, I think the pattern where you have prefixed numbers in the file name has only benefits and virtually no drawbacks. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
