Consistent file naming for search optimization¶
Now that the migration to RST has settled down, we can see that using the former xml:id for file names meant that some RST file names use underbar (_) as space indicators and some RST file names use hyphen (-) as space indicators.
Our conventions are to use hyphens for all RST files so that the resulting built HTML files are human-readable and search-engine-readable.
Update all files in the openstack-manuals repository, a guide at a time, to match our convention of using hyphens for RST file names.
Change any RST file names using underscore to use hyphen instead. Do not change file names if they use hyphens for spacing.
Change any folder names using underscore if and only if the folder results in output on a URL that contains an underscore.
Do not change image or figure file names.
Change any hyperlinks that refer to underscore-named files.
Redirect any old file names to new file names on the web server itself in the
Keep the file names as-is and change our convention to use either hyphens or underscores. This results in decreased findability for files on the site.
- admin-guide: Anne Gentle
- cli-reference: Kato Tomoyuki
- config-reference: Kato Tomoyuki
- common: Akihiro Motoki
- user-guide: Mariia Zlatkova
- ops-guide: Olena Logvinova
- backporting link fixes: Akihiro Motoki
Change file names and links in:
- cli-reference (glance_property_keys.rst is the only file)
These guides have no need to change file names:
Change links in stable/mitaka and stable/liberty branches that go to changed file names due to changes in non-versioned deliverables by backporting link changes.
Update the sitemap.xml file to ensure all new file names are in the sitemap.
Coordination of efforts and landing patches.
Test changed file names for no broken links resulting.
To get the list of Work Items I ran this type of search:
ls ~/src/openstack-manuals/doc/user-guide/source/ | grep _