Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add glossary section. #4

Open
faultyserver opened this issue Apr 8, 2017 · 0 comments
Open

Add glossary section. #4

faultyserver opened this issue Apr 8, 2017 · 0 comments

Comments

@faultyserver
Copy link
Member

There are a number of domain-specific terms and generic terms that have a very specific meaning such as Identifier, DateTime, and visit that should be documented somewhere.

For example, specifying that timetable.visits_between takes two DateTime arguments and returns a list of visits does not mean the arguments/return values are of those types, but rather than they meet the structural requirements of those types. In this case, a DateTime is a String in the format YYYYMMDD HH:mm:ss, and a visit is a tuple in the format (eta, etd, route, headsign).

Right now, users have to interpolate the meaning of these terms from topic descriptions and samples, which is not something that can always been relied upon. Giving these terms complete definitions would make this a non-issue, so long as users know where to look up these terms.

Adding a "Glossary" section would suit this need, and could be displayed inline with topics in the jump menu for easy access.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

1 participant